# PocketSmith MCP Server

An MCP (Model Context Protocol) server for the PocketSmith personal finance API. Enables Claude Desktop, Claude Code, and other MCP clients to manage accounts, transactions, budgets, categories, and financial analysis.

## Features

- **Accounts & Institutions**: Manage bank accounts and financial institutions
- **Transactions**: Create, search, update, and categorize transactions
- **Budgets & Analysis**: View budget summaries and trend analysis
- **Categories & Rules**: Organize transactions with categories and auto-categorization rules
- **Events & Forecasting**: Manage recurring events and clear forecast caches
- **Attachments**: Attach files to transactions

## Installation

### From Source

1. Clone this repository
2. Install dependencies:
   ```bash
   npm install
   ```
3. Build the project:
   ```bash
   npm run build
   ```

## Configuration

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `POCKETSMITH_API_TOKEN` | Yes | — | API token from your PocketSmith account |
| `POCKETSMITH_USER_ID` | No | — | User ID (auto-detected from token if omitted) |
| `POCKETSMITH_API_BASE_URL` | No | `https://api.pocketsmith.com/v2` | Custom API endpoint |

Create a `.env` file or set these in your shell environment.

To generate an API token: PocketSmith Settings > Security > Manage Developer Keys.

## Usage with Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "pocketsmith": {
      "command": "node",
      "args": ["/path/to/pocketsmith-mcp/build/index.js"],
      "env": {
        "POCKETSMITH_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

## Usage with Claude Code

```bash
claude mcp add pocketsmith -- node /path/to/pocketsmith-mcp/build/index.js
```

## Available Tools

### Users
`get_me`, `get_user`, `update_user`

### Institutions
`list_institutions`, `create_institution`, `get_institution`, `update_institution`, `delete_institution`

### Accounts
`list_accounts`, `create_account`, `get_account`, `update_account`, `delete_account`, `reorder_accounts`, `list_institution_accounts`

### Transaction Accounts
`list_transaction_accounts`, `get_transaction_account`, `update_transaction_account`

### Transactions
`list_transactions`, `list_account_transactions`, `list_category_transactions`, `list_transaction_account_transactions`, `create_transaction`, `get_transaction`, `update_transaction`, `delete_transaction`

### Categories
`list_categories`, `create_category`, `get_category`, `update_category`, `delete_category`

### Category Rules
`list_category_rules`, `create_category_rule`

### Budgets & Analysis
`list_budget`, `get_budget_summary`, `get_trend_analysis`, `delete_forecast_cache`

### Events
`list_events`, `list_scenario_events`, `create_event`, `get_event`, `update_event`, `delete_event`

### Attachments
`list_attachments`, `list_transaction_attachments`, `create_attachment`, `assign_attachment`, `unassign_attachment`, `get_attachment`, `update_attachment`, `delete_attachment`

### Reference
`list_currencies`, `get_currency`, `list_time_zones`, `list_labels`, `list_saved_searches`

## Development

- `npm run dev` — Watch mode with TypeScript compilation
- `npm run build` — Build the project
- `npm start` — Start the built server

## License

MIT