Pocketsmith Mcp

Pocketsmith MCP Server

A comprehensive Model Context Protocol (MCP) server for the Pocketsmith personal finance API. Transform your AI assistant into a powerful financial management tool with access to accounts, budgets, transactions, and more.

[](https://www.python.org/downloads/) [](https://opensource.org/licenses/MIT)

> Personal project — not published to PyPI. Install from source (see below).

✨ Features

💰 Account Management

• View all account balances (checking, savings, credit cards, investments)
• Get detailed account information with transaction history
• Track net worth across multiple accounts

📊 Budget & Analysis

• Get budget summaries for any time period
• Analyze per-category spending vs. budgets
• View spending trends across categories
• Compare actual vs. forecasted amounts

💳 Transaction Management

• List, search, and filter transactions
• Create new transactions (log cash purchases, manual entries)
• Update transaction details (categorize, add notes, set labels)
• Delete duplicate or incorrect transactions
• Filter by account, category, date range, or review status

📁 Category Management

• List all categories with hierarchical structure
• Create new categories and subcategories
• Set up automatic categorization rules
• Organize spending into custom categories

🔄 Recurring Transactions

• View upcoming bills and recurring expenses
• Create recurring events (rent, subscriptions, paychecks)
• Forecast future cash flow
• Manage budget scenarios

🏷️ Labels & Organization

• List and manage transaction labels
• Tag transactions for easy filtering
• Track tax-deductible expenses, business spending, etc.

📦 Installation

Install from source

git clone https://github.com/dannyshaw/pocketsmith-mcp.git
cd pocketsmith-mcp
pip install -e .

Or run directly with uv from the source directory (no install needed) — configure your MCP client to invoke:

uv --directory /path/to/pocketsmith-mcp run pocketsmith-mcp

🔑 Configuration

Get Your API Key

1. Log in to Pocketsmith
2. Go to Settings → API & Developers
3. Click Generate New API Key
4. Copy your API key

⚠️ Security: Treat your API key like a password. It has full access to your financial data.

Set Environment Variable

export POCKETSMITH_API_KEY=your_api_key_here

Or create a .env file:

echo "POCKETSMITH_API_KEY=your_api_key_here" > .env

🚀 Usage

With Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "pocketsmith": {
      "command": "uvx",
      "args": ["pocketsmith-mcp"],
      "env": {
        "POCKETSMITH_API_KEY": "your_api_key_here"
      }
    }
  }
}

With Claude Code

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pocketsmith": {
      "command": "pocketsmith-mcp",
      "env": {
        "POCKETSMITH_API_KEY": "your_api_key_here"
      }
    }
  }
}

Standalone

Run the server directly:

pocketsmith-mcp

💬 Example Conversations

Once configured, you can ask your AI assistant:

Account & Budget Queries

• "What are my account balances?"
• "Show me my credit card balance"
• "Am I over budget this month?"
• "What's my spending trend for groceries over the last 3 months?"

Transaction Management

• "List transactions from my checking account this week"
• "Log a $50 cash purchase at the grocery store"
• "Categorize that Amazon transaction as Household"
• "Delete transaction #12345"

Bills & Recurring Expenses

• "What bills are coming up this month?"
• "Create a recurring monthly rent payment of $2000"
• "Show me all my subscriptions"

Categories & Organization

• "Create a new category called 'Pet Expenses'"
• "Show me all transactions in the Dining Out category"
• "Set up a rule to auto-categorize Starbucks as Coffee"

🛠️ Available Tools (23 total)

Account Tools

| Tool | Description | |------|-------------| | pocketsmith_list_accounts | List all accounts with balances | | pocketsmith_get_account | Get detailed account information | | pocketsmith_list_transaction_accounts | List transaction accounts with details |

Budget & Analysis Tools

| Tool | Description | |------|-------------| | pocketsmith_get_budget_summary | Get budget summary for a date range | | pocketsmith_list_budget | Per-category budget analysis | | pocketsmith_get_trend_analysis | Spending trends across categories |

Transaction Tools

| Tool | Description | |------|-------------| | pocketsmith_list_transactions | List transactions with filters | | pocketsmith_list_transactions_by_account | Filter transactions by account | | pocketsmith_list_transactions_by_category | Filter transactions by category | | pocketsmith_get_transaction | Get transaction details | | pocketsmith_create_transaction | Create new transaction | | pocketsmith_update_transaction | Update transaction details | | pocketsmith_delete_transaction | Delete a transaction | | pocketsmith_search_transactions | Search by keyword | | pocketsmith_categorize_transaction | Quick categorization |

Category Tools

| Tool | Description | |------|-------------| | pocketsmith_list_categories | List all categories | | pocketsmith_create_category | Create new category | | pocketsmith_list_category_rules | List auto-categorization rules | | pocketsmith_create_category_rule | Create categorization rule |

Event Tools (Recurring Transactions)

| Tool | Description | |------|-------------| | pocketsmith_list_events | List recurring transactions | | pocketsmith_create_event | Create recurring transaction |

Other Tools

| Tool | Description | |------|-------------| | pocketsmith_list_labels | List all transaction labels | | pocketsmith_get_status | Check connection status |

🔒 Security

This Server Can

• ✅ Read all your financial data (transactions, accounts, balances)
• ✅ Create, update, and delete transactions
• ✅ Modify categories and create rules
• ✅ Access budget and forecast data

Security Best Practices

• ✅ Store API keys in environment variables (never in code)
• ✅ Use different API keys for development vs. production
• ✅ Rotate API keys periodically
• ✅ Only use with trusted AI assistants on secure machines
• ❌ Never commit API keys to version control
• ❌ Never share API keys publicly

See [SECURITY.md](SECURITY.md) for detailed security information.

📊 API Coverage

20 out of 44 Pocketsmith API endpoints (45%)

Focused on the most useful endpoints for personal finance management:

• ✅ User & account management
• ✅ Transaction CRUD operations
• ✅ Budget & trend analysis
• ✅ Category management
• ✅ Recurring events/bills
• ✅ Labels & organization

🧪 Development

Setup

# Clone repository
git clone https://github.com/dannyshaw/pocketsmith-mcp.git
cd pocketsmith-mcp

# Install dependencies
uv sync

# Run tests
pytest

# Run tests with coverage
pytest --cov=src/pocketsmith_mcp

# Lint and format
ruff check .
ruff format .

# Type check
mypy src

Testing

# Run all tests
pytest -v

# Run specific test file
pytest tests/test_client.py -v

# Run with coverage report
pytest --cov=src/pocketsmith_mcp --cov-report=html

Project Structure

pocketsmith-mcp/
├── src/pocketsmith_mcp/
│   ├── __init__.py      # Package initialization
│   ├── client.py        # Pocketsmith API client
│   ├── config.py        # Configuration settings
│   └── server.py        # MCP server implementation
├── tests/
│   ├── conftest.py      # Test fixtures
│   └── test_client.py   # Client tests
├── pyproject.toml       # Project configuration
├── README.md            # This file
└── SECURITY.md          # Security documentation

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Write tests for your changes
4. Ensure all tests pass (pytest)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

📝 License

MIT License - see [LICENSE](LICENSE) for details.

🙏 Acknowledgments

• Built with the Model Context Protocol
• Powered by the Pocketsmith API
• Designed for use with Claude

📞 Support

• Issues: GitHub Issues
• Security: See [SECURITY.md](SECURITY.md)
• Discussions: GitHub Discussions

🗺️ Roadmap

Future enhancements:

• [ ] Attachment management
• [ ] Institution connections management
• [ ] Budget calendar export
• [ ] Spending analytics and insights
• [ ] Multi-currency support enhancements
• [ ] Batch transaction operations

---

Made with ❤️ for personal finance management

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dannyshaw
• Source: dannyshaw/pocketsmith-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.