monarch-mcp-jamiew 0.3.1__tar.gz

monarch_mcp_jamiew-0.3.1/.gitignore

@@ -0,0 +1,78 @@
+# Environment variables
+.env*
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+.venv/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+
+# MyPy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# UV
+uv.lock
+
+# Logs
+*.log
+
+# Session files
+.monarchmoney_session
+.mm/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+Thumbs.db
+ehthumbs.db
+
+# Newish
+logs.sh
+.claude/settings.local.json
+
+# MCP Registry
+.mcpregistry_*

monarch_mcp_jamiew-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jamie Dubs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

monarch_mcp_jamiew-0.3.1/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: monarch-mcp-jamiew
+Version: 0.3.1
+Summary: MCP server for Monarch Money personal finance
+Project-URL: Homepage, https://github.com/jamiew/monarch-mcp
+Project-URL: Repository, https://github.com/jamiew/monarch-mcp
+Project-URL: Issues, https://github.com/jamiew/monarch-mcp/issues
+Author-email: Jamie Dubs <jamie@jamiedubs.com>
+License: MIT
+License-File: LICENSE
+Keywords: budgeting,finance,mcp,model-context-protocol,monarch-money,personal-finance
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.10
+Requires-Dist: mcp[cli]<2,>=1.26.0
+Requires-Dist: monarchmoneycommunity
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: python-dateutil>=2.9.0.post0
+Requires-Dist: structlog>=25.5.0
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.jamiew/monarch-mcp -->
+# Monarch Money MCP Server
+
+An [MCP](https://modelcontextprotocol.io/) server for [Monarch Money](https://www.monarchmoney.com/) — gives AI assistants like Claude access to your financial accounts, transactions, budgets, and more.
+
+Originally forked from [@colvint/monarch-money-mcp](https://github.com/colvint/monarch-money-mcp) but has diverged significantly with a full rewrite, many new features, and a modern FastMCP architecture.
+
+Built with the [MonarchMoney](https://github.com/hammem/monarchmoney) Python library by [@hammem](https://github.com/hammem) — a fantastic unofficial API for Monarch Money with full MFA support. We currently use the [community fork](https://github.com/bradleyseanf/monarchmoneycommunity) by [@bradleyseanf](https://github.com/bradleyseanf) which tracks the latest Monarch Money API changes.
+
+## Features
+
+- **19 tools** covering accounts, transactions, budgets, cashflow, investments, categories, goals, net worth, recurring transactions, and more
+- **MCP resources** for quick access to categories, accounts, and institutions
+- **MCP prompts** for guided financial analysis workflows
+- **Smart output formatting** — compact transaction format reduces token usage by ~80%
+- **Natural language dates** — "last month", "30 days ago", "this year" all work
+- **Batch operations** — parallel multi-account queries, bulk transaction updates
+- **Spending analysis** — multi-month trend analysis with category/account breakdowns
+- **Tool annotations** — proper read/write metadata for MCP clients
+
+## Setup
+
+### 1. Install dependencies
+
+```bash
+cd /path/to/monarch-mcp
+uv sync
+```
+
+### 2. Configure your MCP client
+
+Add to your `.mcp.json` (Claude Desktop, Claude Code, etc.):
+
+```json
+{
+  "mcpServers": {
+    "monarch-money": {
+      "command": "/path/to/uv",
+      "args": [
+        "--directory",
+        "/path/to/monarch-mcp",
+        "run",
+        "python",
+        "server.py"
+      ],
+      "env": {
+        "MONARCH_EMAIL": "your-email@example.com",
+        "MONARCH_PASSWORD": "your-password",
+        "MONARCH_MFA_SECRET": "your-mfa-secret-key"
+      }
+    }
+  }
+}
+```
+
+Use absolute paths — find yours with `which uv` and `pwd`.
+
+### 3. Get your MFA secret
+
+1. Go to Monarch Money settings and enable 2FA
+2. When shown the QR code, look for "Can't scan?" or "Enter manually"
+3. Copy the secret key (a string like `T5SPVJIBRNPNNINFSH5W7RFVF2XYADYX`)
+4. Use this as your `MONARCH_MFA_SECRET`
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_accounts` | List accounts with balances |
+| `get_transactions` | Transactions with date/account/category filtering |
+| `search_transactions` | Search by merchant name or keyword |
+| `get_transaction_categories` | Category list (compact by default) |
+| `create_transaction` | Create a manual transaction |
+| `update_transaction` | Update a single transaction |
+| `update_transactions_bulk` | Update multiple transactions in parallel |
+| `get_budgets` | Budget data and spending analysis |
+| `get_cashflow` | Income and expense analysis |
+| `get_account_holdings` | Investment holdings |
+| `get_account_history` | Account balance history |
+| `get_institutions` | Linked financial institutions |
+| `get_recurring_transactions` | Recurring transaction detection |
+| `set_budget_amount` | Set a budget category amount |
+| `create_manual_account` | Create a manually-tracked account |
+| `refresh_accounts` | Trigger account data refresh |
+| `get_complete_financial_overview` | Combined 5-API call in parallel |
+| `analyze_spending_patterns` | Multi-month trend analysis |
+| `get_usage_analytics` | Tool usage stats and optimization tips |
+
+### Transaction format
+
+By default, transactions return a compact format with the fields that matter:
+
+```json
+{
+  "id": "123456789012345678",
+  "date": "2025-03-15",
+  "amount": -12.50,
+  "merchant": "Corner Deli",
+  "plaidName": "CORNER DELI NYC",
+  "category": "Restaurants & Bars",
+  "categoryId": "cat_001",
+  "account": "Main Credit Card",
+  "needsReview": true
+}
+```
+
+`pending` and `notes` are included only when present. Set `verbose=True` on any tool for the full API response with all metadata.
+
+## Session management
+
+Sessions are cached in a `.mm` directory for faster subsequent logins. If you hit auth issues:
+
+- Delete `.mm/session.pickle` to clear the cached session
+- Set `MONARCH_FORCE_LOGIN=true` in your env config to force a fresh login
+- Make sure your system clock is accurate (required for TOTP)
+
+## Development
+
+### Local setup
+
+Create a `.env` file (git-ignored):
+
+```bash
+MONARCH_EMAIL="your-email@example.com"
+MONARCH_PASSWORD="your-password"
+MONARCH_MFA_SECRET="YOUR_TOTP_SECRET_KEY"
+```
+
+### Tests
+
+```bash
+uv run pytest tests/ -v                          # unit tests (no creds needed)
+uv run pytest tests/test_integration.py -v        # integration tests (needs .env)
+uv run scripts/health_check.py                    # quick API connectivity check
+```
+
+### CI checks
+
+Run all checks locally (same as GitHub Actions CI):
+
+```bash
+uv run python scripts/ci.py
+```
+
+### Log analysis
+
+Tools for measuring and optimizing token usage across MCP sessions:
+
+```bash
+uv run scripts/analyze_logs.py                    # full report
+uv run scripts/analyze_logs.py --json             # JSON output
+uv run scripts/eval_session.py snapshot           # mark log position
+# ... use tools in Claude ...
+uv run scripts/eval_session.py analyze            # analyze new entries
+```
+
+## Security
+
+> **Warning**: Monarch Money does not provide an official API. This server uses unofficial API access that requires your actual account credentials. Use with appropriate caution.
+
+- Your credentials have full account access — treat them like passwords
+- The MFA secret (TOTP key) provides ongoing access
+- Session files in `.mm/` contain auth tokens — keep them secure
+- Never commit `.env` or `.mcp.json` files to version control
+- This is an unofficial API — Monarch Money could change or restrict access at any time
+
+## Credits
+
+This project started as a fork of [colvint/monarch-money-mcp](https://github.com/colvint/monarch-money-mcp) by [@colvint](https://github.com/colvint). Thanks for the original implementation!
+

monarch_mcp_jamiew-0.3.1/README.md

@@ -0,0 +1,170 @@
+<!-- mcp-name: io.github.jamiew/monarch-mcp -->
+# Monarch Money MCP Server
+
+An [MCP](https://modelcontextprotocol.io/) server for [Monarch Money](https://www.monarchmoney.com/) — gives AI assistants like Claude access to your financial accounts, transactions, budgets, and more.
+
+Originally forked from [@colvint/monarch-money-mcp](https://github.com/colvint/monarch-money-mcp) but has diverged significantly with a full rewrite, many new features, and a modern FastMCP architecture.
+
+Built with the [MonarchMoney](https://github.com/hammem/monarchmoney) Python library by [@hammem](https://github.com/hammem) — a fantastic unofficial API for Monarch Money with full MFA support. We currently use the [community fork](https://github.com/bradleyseanf/monarchmoneycommunity) by [@bradleyseanf](https://github.com/bradleyseanf) which tracks the latest Monarch Money API changes.
+
+## Features
+
+- **19 tools** covering accounts, transactions, budgets, cashflow, investments, categories, goals, net worth, recurring transactions, and more
+- **MCP resources** for quick access to categories, accounts, and institutions
+- **MCP prompts** for guided financial analysis workflows
+- **Smart output formatting** — compact transaction format reduces token usage by ~80%
+- **Natural language dates** — "last month", "30 days ago", "this year" all work
+- **Batch operations** — parallel multi-account queries, bulk transaction updates
+- **Spending analysis** — multi-month trend analysis with category/account breakdowns
+- **Tool annotations** — proper read/write metadata for MCP clients
+
+## Setup
+
+### 1. Install dependencies
+
+```bash
+cd /path/to/monarch-mcp
+uv sync
+```
+
+### 2. Configure your MCP client
+
+Add to your `.mcp.json` (Claude Desktop, Claude Code, etc.):
+
+```json
+{
+  "mcpServers": {
+    "monarch-money": {
+      "command": "/path/to/uv",
+      "args": [
+        "--directory",
+        "/path/to/monarch-mcp",
+        "run",
+        "python",
+        "server.py"
+      ],
+      "env": {
+        "MONARCH_EMAIL": "your-email@example.com",
+        "MONARCH_PASSWORD": "your-password",
+        "MONARCH_MFA_SECRET": "your-mfa-secret-key"
+      }
+    }
+  }
+}
+```
+
+Use absolute paths — find yours with `which uv` and `pwd`.
+
+### 3. Get your MFA secret
+
+1. Go to Monarch Money settings and enable 2FA
+2. When shown the QR code, look for "Can't scan?" or "Enter manually"
+3. Copy the secret key (a string like `T5SPVJIBRNPNNINFSH5W7RFVF2XYADYX`)
+4. Use this as your `MONARCH_MFA_SECRET`
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_accounts` | List accounts with balances |
+| `get_transactions` | Transactions with date/account/category filtering |
+| `search_transactions` | Search by merchant name or keyword |
+| `get_transaction_categories` | Category list (compact by default) |
+| `create_transaction` | Create a manual transaction |
+| `update_transaction` | Update a single transaction |
+| `update_transactions_bulk` | Update multiple transactions in parallel |
+| `get_budgets` | Budget data and spending analysis |
+| `get_cashflow` | Income and expense analysis |
+| `get_account_holdings` | Investment holdings |
+| `get_account_history` | Account balance history |
+| `get_institutions` | Linked financial institutions |
+| `get_recurring_transactions` | Recurring transaction detection |
+| `set_budget_amount` | Set a budget category amount |
+| `create_manual_account` | Create a manually-tracked account |
+| `refresh_accounts` | Trigger account data refresh |
+| `get_complete_financial_overview` | Combined 5-API call in parallel |
+| `analyze_spending_patterns` | Multi-month trend analysis |
+| `get_usage_analytics` | Tool usage stats and optimization tips |
+
+### Transaction format
+
+By default, transactions return a compact format with the fields that matter:
+
+```json
+{
+  "id": "123456789012345678",
+  "date": "2025-03-15",
+  "amount": -12.50,
+  "merchant": "Corner Deli",
+  "plaidName": "CORNER DELI NYC",
+  "category": "Restaurants & Bars",
+  "categoryId": "cat_001",
+  "account": "Main Credit Card",
+  "needsReview": true
+}
+```
+
+`pending` and `notes` are included only when present. Set `verbose=True` on any tool for the full API response with all metadata.
+
+## Session management
+
+Sessions are cached in a `.mm` directory for faster subsequent logins. If you hit auth issues:
+
+- Delete `.mm/session.pickle` to clear the cached session
+- Set `MONARCH_FORCE_LOGIN=true` in your env config to force a fresh login
+- Make sure your system clock is accurate (required for TOTP)
+
+## Development
+
+### Local setup
+
+Create a `.env` file (git-ignored):
+
+```bash
+MONARCH_EMAIL="your-email@example.com"
+MONARCH_PASSWORD="your-password"
+MONARCH_MFA_SECRET="YOUR_TOTP_SECRET_KEY"
+```
+
+### Tests
+
+```bash
+uv run pytest tests/ -v                          # unit tests (no creds needed)
+uv run pytest tests/test_integration.py -v        # integration tests (needs .env)
+uv run scripts/health_check.py                    # quick API connectivity check
+```
+
+### CI checks
+
+Run all checks locally (same as GitHub Actions CI):
+
+```bash
+uv run python scripts/ci.py
+```
+
+### Log analysis
+
+Tools for measuring and optimizing token usage across MCP sessions:
+
+```bash
+uv run scripts/analyze_logs.py                    # full report
+uv run scripts/analyze_logs.py --json             # JSON output
+uv run scripts/eval_session.py snapshot           # mark log position
+# ... use tools in Claude ...
+uv run scripts/eval_session.py analyze            # analyze new entries
+```
+
+## Security
+
+> **Warning**: Monarch Money does not provide an official API. This server uses unofficial API access that requires your actual account credentials. Use with appropriate caution.
+
+- Your credentials have full account access — treat them like passwords
+- The MFA secret (TOTP key) provides ongoing access
+- Session files in `.mm/` contain auth tokens — keep them secure
+- Never commit `.env` or `.mcp.json` files to version control
+- This is an unofficial API — Monarch Money could change or restrict access at any time
+
+## Credits
+
+This project started as a fork of [colvint/monarch-money-mcp](https://github.com/colvint/monarch-money-mcp) by [@colvint](https://github.com/colvint). Thanks for the original implementation!
+

monarch_mcp_jamiew-0.3.1/pyproject.toml

@@ -0,0 +1,153 @@
+[project]
+name = "monarch-mcp-jamiew"
+version = "0.3.1"
+description = "MCP server for Monarch Money personal finance"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Jamie Dubs", email = "jamie@jamiedubs.com" },
+]
+keywords = [
+    "mcp",
+    "model-context-protocol",
+    "monarch-money",
+    "finance",
+    "budgeting",
+    "personal-finance",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial",
+]
+dependencies = [
+    "mcp[cli]>=1.26.0,<2",
+    "monarchmoneycommunity",
+    "pydantic>=2.12.5",
+    "python-dateutil>=2.9.0.post0",
+    "structlog>=25.5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/jamiew/monarch-mcp"
+Repository = "https://github.com/jamiew/monarch-mcp"
+Issues = "https://github.com/jamiew/monarch-mcp/issues"
+
+[project.scripts]
+monarch-mcp-jamiew = "server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+only-include = ["server.py"]
+
+[tool.hatch.build.targets.sdist]
+only-include = [
+    "server.py",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+
+[dependency-groups]
+dev = [
+    "mypy>=1.19.0",
+    "pytest>=9.0.0",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.15.0",
+    "types-python-dateutil>=2.9.0.20260302",
+]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+strict_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+show_error_codes = true
+ignore_missing_imports = true
+# Disable specific errors:
+# - misc: Various untyped external library issues
+# - unreachable: Defensive runtime type checks are intentional
+# - untyped-decorator: MCP library decorators (@mcp.tool, @mcp.resource, @mcp.prompt) lack type stubs
+disable_error_code = ["misc", "unreachable", "untyped-decorator"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = ["-v", "--tb=short", "--strict-markers"]
+asyncio_mode = "auto"
+markers = [
+    "unit: Unit tests",
+    "integration: Integration tests", 
+    "slow: Slow running tests"
+]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "F",      # pyflakes
+    "I",      # isort
+    "B",      # flake8-bugbear
+    "C4",     # flake8-comprehensions
+    "UP",     # pyupgrade
+    "SIM",    # flake8-simplify
+]
+ignore = [
+    "E501",   # line too long (handled by formatter)
+    "B008",   # do not perform function calls in argument defaults
+    "SIM108", # use ternary operator instead of if-else
+    "E402",   # module import not at top (needed for conditional imports)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = [
+    "F841",   # unused variables (often intentional in mocks)
+    "SIM117", # multiple with statements (clearer in tests)
+]
+"scripts/*" = [
+    "F841",   # unused variables (often for side effects)
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["server"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+
+[tool.coverage.run]
+source = ["."]
+omit = ["tests/*", ".venv/*"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if __name__ == .__main__.:",
+    "raise NotImplementedError",
+]
+
+[tool.uv.sources]
+monarchmoneycommunity = { git = "https://github.com/bradleyseanf/monarchmoneycommunity", rev = "main" }