pocketsmith-mcp 1.0.0

Production-ready MCP server for PocketSmith personal finance API

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

Configuration

1. Get your API key from PocketSmith Settings

2. Set your environment variable:

export POCKETSMITH_API_KEY=your_api_key_here

3. 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

User Management

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

Account Management

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

Transaction Accounts

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

Transactions

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

Categories

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

Budgeting

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

Institutions

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

Events (Budget Calendar)

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

Attachments

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

Labels & Searches

Tool	Description
list_labels	List all labels
list_saved_searches	List saved searches

Utilities

Tool	Description
list_currencies	List supported currencies
list_time_zones	List supported time zones

---

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_rate_limiter.py
│   ├── test_circuit_breaker.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/your-repo/pocketsmith-mcp.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.

---

Made with Python and FastMCP