pocketsmith-mcp

<p align="center"> <h1 align="center">PocketSmith MCP Server</h1> <p align="center"> <strong>A production-ready MCP server for the PocketSmith personal finance API</strong> </p> </p>

<p align="center"> <img src="assets/demo.gif" alt="PocketSmith MCP Demo" width="700"> </p>

<p align="center"> <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+"></a> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License: MIT"></a> <a href="https://pypi.org/project/pocketsmith-mcp/"><img src="https://img.shields.io/pypi/v/pocketsmith-mcp?color=blue" alt="PyPI"></a> <img src="https://img.shields.io/badge/tests-180%20passed-brightgreen" alt="Tests: 180 passed"> <img src="https://img.shields.io/badge/coverage-86%25-brightgreen" alt="Coverage: 86%"> </p>

<p align="center"> <a href="#features">Features</a> • <a href="#quick-start">Quick Start</a> • <a href="#available-tools">Tools</a> • <a href="#testing">Testing</a> • <a href="#development">Development</a> </p>

---

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"

<p align="center"> <img src="assets/api-key-step1-security-integrations.png" alt="Navigate to Security & Integrations" width="500"> </p>

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

<p align="center"> <img src="assets/api-key-step2-create-key.png" alt="Create Developer Key" width="500"> </p>

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

<details> <summary><strong>User Management</strong></summary>

Tool	Description
get_current_user	Get authenticated user info
get_user	Get user by ID
update_user	Update user settings

</details>

<details> <summary><strong>Account Management</strong></summary>

Tool	Description
list_accounts	List all accounts
get_account	Get account details
update_account	Update account
delete_account	Delete account

</details>

<details> <summary><strong>Transaction Accounts</strong></summary>

Tool	Description
list_transaction_accounts	List transaction accounts
get_transaction_account	Get transaction account details
update_transaction_account	Update transaction account

</details>

<details> <summary><strong>Transactions</strong></summary>

Tool	Description
list_transactions	List transactions with filters
get_transaction	Get transaction details
create_transaction	Create new transaction
update_transaction	Update transaction
delete_transaction	Delete transaction

</details>

<details> <summary><strong>Categories</strong></summary>

Tool	Description
list_categories	List all categories
get_category	Get category details
create_category	Create new category
update_category	Update category
delete_category	Delete category

</details>

<details> <summary><strong>Budgeting</strong></summary>

Tool	Description
get_budget	Get budget data
get_budget_summary	Get budget summary
get_trend_analysis	Get spending trends
clear_forecast_cache	Clear forecast cache

</details>

<details> <summary><strong>Institutions</strong></summary>

Tool	Description
list_institutions	List financial institutions
get_institution	Get institution details
create_institution	Create institution
update_institution	Update institution
delete_institution	Delete institution

</details>

<details> <summary><strong>Events (Budget Calendar)</strong></summary>

Tool	Description
list_events	List budget events
get_event	Get event details
create_event	Create budget event
update_event	Update event
delete_event	Delete event

</details>

<details> <summary><strong>Attachments</strong></summary>

Tool	Description
list_attachments	List attachments
get_attachment	Get attachment details
create_attachment	Upload attachment
update_attachment	Update attachment
delete_attachment	Delete attachment

</details>

<details> <summary><strong>Labels & Searches</strong></summary>

Tool	Description
list_labels	List all labels
list_saved_searches	List saved searches

</details>

<details> <summary><strong>Utilities</strong></summary>

Tool	Description
list_currencies	List supported currencies
list_time_zones	List supported time zones

</details>

---

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

Variable	Required	Default	Description
POCKETSMITH_API_KEY	Yes	-	Your PocketSmith API key
DEBUG	No	false	Enable debug logging
API_TIMEOUT	No	30	Request timeout (seconds)
MAX_RETRIES	No	3	Retry attempts for failed requests
RATE_LIMIT_PER_MINUTE	No	60	API rate limit

---

License

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

---

<p align="center"> Made with Python and FastMCP </p>