A personal financial management system that helps you track expenses and income using a Telegram bot connected to your own Google Sheets.
This project implements a personal financial management system consisting of:
- A Telegram bot for easy access from any device
- Google Sheets integration to store and manage your financial data
- OAuth 2.0 authentication for secure access to your own spreadsheets
- SQLite Database to store encrypted tokens and user preferences
- Custom category management to personalize expense tracking
Note: This is a beta version (0.1) released for testing and feedback.
- OAuth 2.0 Authentication: Securely access your own Google Sheets without sharing permissions
- Encrypted Token Storage: Secure token management using Fernet cryptography
- Custom Categories: Define your own income and expense categories
- Guided Transaction Flow: Intuitive interface with buttons for logging transactions
- Multi-User Support: Each user accesses their own spreadsheets and uses their own categories
- Modern Type Hints: Full use of Python 3.9+ typing features
- Python 3.13+
- Telegram bot token (from @BotFather)
- Google Cloud Platform OAuth 2.0 credentials
uvpackage manager (required)
-
Clone the repository:
git clone https://github.com/lmontanares/midas-sheet.git cd midas-sheet -
Configure environment variables:
cp .env.example .env # Edit .env with your configuration values -
Generate a Fernet encryption key:
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" # Copy the output to OAUTH_ENCRYPTION_KEY in your .env file
-
Set up Google Cloud OAuth:
- Create a project in Google Cloud Platform
- Enable Google Sheets and Google Drive APIs
- Create OAuth 2.0 credentials for a web application
- Add Redirect URI:
http://localhost:8000/oauth2callback(or your configured host/port) - Download credentials and save as
oauth_credentials.jsonin the project root
-
Run the application:
uv run python main.py
Note:
uv runautomatically handles virtual environment creation, dependency installation, and activation. -
Start interacting with your bot on Telegram!
/start- Begin interaction with the bot/help- Display available commands and usage info/auth- Start the OAuth authentication process/sheet- Select a specific spreadsheet/logout- Revoke access and log out/add- Add a new expense or income/categories- View your current expense/income categories/editcat- Edit your categories (using YAML import/export)/resetcat- Reset categories to default values
The transaction flow (/add command) follows these steps:
- Select transaction type (income or expense)
- Select category from your custom list
- Select subcategory for expenses
- Enter the amount
- Optionally add comments
- Transaction is recorded in your selected Google Sheet
Users can customize categories through:
- View: Use
/categoriesto see current categories - Edit: Use
/editcatto import/export categories as YAML files - Reset: Use
/resetcatto revert to default categories
/midas-sheet/
│
├── src/ # Source code
│ ├── auth/ # OAuth 2.0 Authentication
│ ├── bot/ # Telegram bot logic
│ ├── config/ # Configurations and category management
│ ├── db/ # Database models and functions
│ ├── server/ # Server for OAuth redirects
│ ├── sheets/ # Google Sheets integration
│ └── utils/ # Common utilities
│
├── tests/ # Automated tests
├── docs/ # Documentation
├── main.py # Main entry point
├── pyproject.toml # Project configuration
└── README.md # This documentation
uv run pytest
# or for coverage report
uv run pytest --cov=src tests/- Follow PEP 8
- Use modern Python 3.9+ typing features
- Document all public functions and methods
- Write tests for new functionality
This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.
- python-telegram-bot library
- gspread for Google Sheets integration
- SQLAlchemy for database ORM
- cryptography for secure token storage
This project was developed with assistance from Large Language Models (LLMs), primarily Claude and Gemini. LLMs were used for code generation, documentation writing, debugging assistance, and architectural guidance. All LLM-generated content has been reviewed and validated by human developers before inclusion in this project.