joho/pocketsmith-mcp

PocketSmith MCP Server

Generated from cyanheads/mcp-ts-template

An MCP (Model Context Protocol) server for managing budgets via the PocketSmith API.

Built on the cyanheads/mcp-ts-template, this server follows a modular architecture with robust error handling, logging, and security features while providing comprehensive PocketSmith integration.

See POCKETSMITH_README.md for complete PocketSmith-specific documentation.

🔒 Security Considerations

⚠️ CRITICAL: This server provides full access to your PocketSmith financial data. Please read our complete Security Guide before installation.

Security Quick Start

• This server handles highly sensitive financial data
• Your PocketSmith API key provides complete access to your financial accounts
• Only use with trusted MCP clients and secure configurations
• Enable confirmation prompts for all financial operations

Essential Security Checklist

• Read the complete SECURITY.md documentation
• Store API key in secure environment variables only
• Use stdio transport for single-user scenarios
• Never add financial operations to auto-approve lists
• Set up regular API key rotation (recommended: every 90 days)
• Monitor your PocketSmith account for unauthorized changes

🚨 Never share your API key or use this server on untrusted systems.

Quick Start

1. Install dependencies:

   npm install
   

2. Set up environment: Copy .env.example to .env and add your PocketSmith API key

3. Build:

   npm run build
   

4. Run:

   npm run start:stdio  # For MCP clients
   npm run start:http   # For web applications
   

Available Tools

Account Management

• get_accounts - View account balances and information
• get_user_summary - Comprehensive financial overview

Transaction Management

• get_transactions - Search and filter transactions with advanced criteria
• get_transaction - Get detailed information about a specific transaction
• create_transaction - Add new transactions with categories and notes
• update_transaction - Modify existing transactions (change payee, amount, category, etc.)
• delete_transaction - Remove transactions (with confirmation)

Category Management

• get_categories - View spending categories and hierarchies
• create_category - Add new spending categories with colors and parent relationships
• update_category - Modify existing categories (rename, recolor, reparent)

Budget Analysis

• get_budgets - Analyze budget vs actual spending performance
• get_budget_summary - Detailed budget analysis with period breakdowns

Recurring Events

• get_recurring_events - View scheduled/recurring transactions and income

Attachments & Receipts

• get_transaction_attachments - View attachments for specific transactions
• get_user_attachments - View all user attachments across transactions
• create_transaction_attachment - Add receipts and documents to transactions

Categorization Rules

• get_category_rules - View automatic categorization rules
• create_category_rule - Create rules for auto-categorizing transactions

Account Details

• get_account_transactions - Get transactions for specific accounts
• get_transaction_accounts - Detailed transaction account information

System Information

• get_currencies - View supported currencies and their formats
• get_institutions - View connected financial institutions

MCP Configuration

For Claude Desktop or other MCP clients:

{
  "mcpServers": {
    "pocketsmith": {
      "command": "node",
      "args": ["/path/to/pocketsmith-mcp/dist/index.js"],
      "env": {
        "POCKETSMITH_API_KEY": "your_api_key_here"
      }
    }
  }
}

---

Built with ❤️ and the Model Context Protocol

---

🚀 Original MCP TypeScript Template Documentation

The following documentation is from the original cyanheads/mcp-ts-template:

Jumpstart your Model Context Protocol (MCP) development with this comprehensive TypeScript Template for building autonomous agents, servers, and clients.

This template provides a solid, beginner-friendly foundation for building all components of the MCP ecosystem, adhering to the MCP 2025-06-18 specification. It includes a powerful agent framework, a fully-featured server, a robust client, production-ready utilities, and clear documentation to get you up and running quickly.

🏛️ Three-Part Architecture

This template is organized into three primary, interconnected components:

1. 🤖 Agent (src/agent/): An autonomous agent framework. The agent can connect to multiple MCP servers, discover their tools, and use them to accomplish complex tasks based on a user's prompt. Use this as a starting point for your agents.
2. 🔌 MCP Server (src/mcp-server/): An extensible MCP server that can host custom tools and resources, making them available to agents and other clients.
3. 💻 MCP Client (src/mcp-client/): A robust client for connecting to and interacting with any MCP-compliant server. The agent uses this client to communicate with the outside world.

✨ Key Features

🌟 Projects Using This Template

This template is already powering several MCP servers, demonstrating its flexibility and robustness:

Note: toolkit-mcp-server was built on an older version of this template and is pending updates.

You can also see my GitHub profile for additional MCP servers I've created.

Quick Start

1. Installation

Clone the repository and install dependencies:

git clone https://github.com/cyanheads/mcp-ts-template.git
cd mcp-ts-template
npm install

2. Build the Project

npm run build
# Or use 'npm run rebuild' for a clean install

3. Running the Components

Running the MCP Server

You can run the included MCP server to make its tools available.

• Via Stdio (Default):

  npm run start:server
  

• Via Streamable HTTP:

  npm run start:server:http
  

Running the Agent

The agent can be run from the command line to perform tasks. It will automatically connect to the servers defined in src/mcp-client/client-config/mcp-config.json. If running the agent, you must have the MCP config set up correctly and your openrouter API key configured in .env.

npm run start:agent "Your prompt here"

# Example:
npm run start:agent "Use the echo tool to say hello world and then get a cat fact."

⚙️ Configuration

Server Configuration (Environment Variables)

Configure the MCP server's behavior using these environment variables:

Client & Agent Configuration

The agent uses the MCP client to connect to servers. This is configured in src/mcp-client/client-config/mcp-config.json. You must list all MCP servers the agent should connect to in this file.

For a detailed guide, see the Client Configuration README.

🏗️ Project Structure

• src/agent/: Contains the core agent framework, including the Agent class and a CLI for running the agent.
• src/mcp-client/: Implements the MCP client logic for connecting to and interacting with external MCP servers.
• src/mcp-server/: Contains the MCP server implementation, including example tools, resources, and transport handlers.
• src/config/: Handles loading and validation of environment variables and application configuration.
• src/services/: Provides reusable modules for integrating with external services (DuckDB, OpenRouter).
• src/types-global/: Defines shared TypeScript interfaces and type definitions.
• src/utils/: A collection of core utilities (logging, error handling, security, etc.).
• src/index.ts: The main entry point for the application, responsible for initializing and starting the MCP server.

Explore the full structure yourself:

See the current file tree in docs/tree.md or generate it dynamically:

npm run tree

🧩 Extending the System

Adding Tools to the Server

For detailed guidance on how to add your own custom Tools and Resources to the MCP server, please see the Server Extension Guide.

Modifying the Agent

The agent's core logic is in src/agent/agent-core/agent.ts. You can modify its system prompt, the models it uses (google/gemini-2.5-flash by default), and its decision-making loop to change its behavior.

🌍 Explore More MCP Resources

Looking for more examples, guides, and pre-built MCP servers? Check out the companion repository:

➡️ cyanheads/model-context-protocol-resources

📜 License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.