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.

Related MCP server: Actual Budget MCP Server

📦 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

Budget & Analysis Tools

Transaction Tools

Category Tools

Event Tools (Recurring Transactions)

Other Tools

🔒 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