ajanderson1/mcp_pocketsmith

PocketSmith MCP Server

A production-ready MCP server for the PocketSmith personal finance API

Features • Quick Start • Tools • Testing • Development

---

Features

• 43 MCP Tools - Complete coverage of PocketSmith API v2 endpoints
• Production Ready - Rate limiting, retry with exponential backoff, circuit breaker
• Universal Compatibility - Works with Claude Desktop, Cursor, and any MCP-compatible client
• Type Safe - Pydantic models for all API entities

---

Quick Start

Installation

# Run directly with uvx (recommended)
uvx pocketsmith-mcp

# Or install with pip
pip install pocketsmith-mcp

Getting Your API Key

1. Navigate to Security & Integrations - Click your profile icon, then select “Security & integrations”

2. Create a Developer Key - Go to “Manage developer keys” and click “Create Key”

Configuration

1. Set your environment variable:

export POCKETSMITH_API_KEY=your_api_key_here

2. Run the server:

uvx pocketsmith-mcp

---

Claude Desktop Integration

Add to your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

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

---

Available Tools

---

Testing

Running Tests

# Run all tests
uv run pytest

# Run with coverage report
uv run pytest --cov=src/pocketsmith_mcp --cov-report=term-missing

# Run specific test file
uv run pytest tests/unit/tools/test_transactions.py

# Run tests by marker
uv run pytest -m unit          # Unit tests only
uv run pytest -m integration   # Integration tests only
uv run pytest -m e2e           # End-to-end tests (requires API key)

Test Structure

tests/
├── unit/                 # Fast, isolated tests with mocked API
│   ├── test_api_client.py
│   ├── test_errors.py
│   ├── test_rate_limiter.py
│   ├── test_circuit_breaker.py
│   ├── test_user_context.py
│   └── tools/            # Tool-specific unit tests
├── integration/          # Tests with mocked HTTP responses
│   ├── test_server.py
│   └── test_tools.py
└── conftest.py           # Shared fixtures

Coverage

The project maintains a 70% coverage threshold. Coverage reports are generated automatically:

uv run pytest --cov=src/pocketsmith_mcp --cov-report=html
open htmlcov/index.html

---

Development

Setup

# Clone the repository
git clone https://github.com/ajanderson1/mcp_pocketsmith.git
cd pocketsmith-mcp

# Install dependencies (including dev)
uv sync --dev

# Copy environment template
cp .env.example .env
# Edit .env and add your API key

Architecture

pocketsmith-mcp/
├── src/pocketsmith_mcp/
│   ├── __main__.py       # Entry point
│   ├── server.py         # FastMCP server setup
│   ├── config.py         # Environment configuration
│   ├── client/           # API client with resilience patterns
│   │   ├── api_client.py     # HTTP client wrapper
│   │   ├── rate_limiter.py   # Token bucket algorithm
│   │   ├── circuit_breaker.py # Fault tolerance
│   │   └── retry.py          # Exponential backoff
│   ├── models/           # Pydantic data models
│   └── tools/            # MCP tool implementations
└── tests/                # Unit and integration tests

API Resilience

The client includes production-grade resilience:

• Rate Limiting - Token bucket algorithm (60 req/min default)
• Retry Logic - Exponential backoff with jitter for transient failures
• Circuit Breaker - Prevents cascade failures during outages

---

Environment Variables

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Made with Python and FastMCP