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.

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

• 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

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

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

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

• 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)

• 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)

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

• get_recurring_events - View scheduled/recurring transactions and income

• 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

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

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

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

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

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.

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.

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.

Clone the repository and install dependencies:

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

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

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

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

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

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.

• 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

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

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.

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

➡️ cyanheads/model-context-protocol-resources

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