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.

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 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 for detailed guidelines.

📝 License

MIT License - see 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
• 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