# Rotki MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with [Rotki](https://rotki.com/) portfolio tracker. This server exposes Rotki's functionality through intuitive, jobs-to-be-done tools for AI assistants like Claude.

## Author

**Dennison Bertram** ([@dennisonbertram](https://github.com/dennisonbertram))
Email: dennison@dapphero.io

## Features

- **7 Production-Ready Tools** for portfolio management
- **Real-time crypto prices** (BTC, ETH, stablecoins, etc.)
- **Portfolio overview** with net worth and allocation
- **Transaction history** with flexible filtering
- **Resource endpoints** for portfolio summaries
- **Input validation** using Zod schemas
- **Comprehensive error handling**
- **stdio transport** for Claude Desktop/Code integration

## Prerequisites

- Node.js 18+
- pnpm 10+
- A running [Rotki](https://rotki.com/) instance (default: `http://127.0.0.1:4242`)

## Installation

```bash
# Clone the repository
git clone https://github.com/dennisonbertram/mcp-rotki.git
cd mcp-rotki

# Install dependencies
pnpm install

# Build the server
pnpm build
```

## Configuration

### Environment Variables

- `ROTKI_MCP_BASE_URL` - Rotki API base URL (default: `http://127.0.0.1:4242/api/1`)
- `ROTKI_MCP_TIMEOUT_MS` - HTTP timeout in milliseconds (default: `120000`)
- `ROTKI_MCP_USER` - Optional: Rotki username for auto-login
- `ROTKI_MCP_PASSWORD` - Optional: Rotki password for auto-login
- `ROTKI_MCP_ALLOW_LOGIN_TOOL` - Enable login tool (default: `false`)

### Claude Desktop/Code Integration

Add to your Claude configuration file:

**macOS**: `~/.config/claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "rotki-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-rotki/dist/server.js"],
      "env": {
        "ROTKI_MCP_BASE_URL": "http://127.0.0.1:4242/api/1",
        "ROTKI_MCP_TIMEOUT_MS": "120000"
      }
    }
  }
}
```

**Important**:
1. Replace `/absolute/path/to/mcp-rotki` with your actual path
2. Restart Claude Desktop/Code after updating the config
3. Ensure Rotki is running and unlocked

## Available Tools

### Portfolio Management

#### `get_portfolio_overview`
Get a complete portfolio snapshot with net worth, allocation, and top positions.

**Parameters:**
- `currency` (optional): Target currency (default: "USD")

**Example:**
```
"Show me my portfolio overview"
```

#### `get_positions`
View open positions across exchanges and blockchain networks.

**Parameters:**
- `include_protocols` (optional): Include DeFi protocol positions

**Example:**
```
"What are my current positions?"
```

#### `get_prices`
Fetch real-time asset prices.

**Parameters:**
- `assets` (required): Array of asset identifiers (e.g., ["BTC", "ETH"])
- `currency` (optional): Target currency (default: "USD")
- `at_time_ms` (optional): Historical timestamp

**Example:**
```
"Get current prices for BTC and ETH"
```

### Transaction History

#### `list_transactions`
List recent transactions within a time window.

**Parameters:**
- `window_days` (optional): Days to look back (1-365, default: 30)
- `limit` (optional): Max results (1-500, default: 200)
- `offset` (optional): Pagination offset

**Example:**
```
"Show me transactions from the last 7 days"
```

#### `find_transactions`
Search transactions with specific filters and time range.

**Parameters:**
- `from_ts_ms` (required): Start timestamp in milliseconds
- `to_ts_ms` (required): End timestamp in milliseconds
- `limit` (optional): Max results
- `offset` (optional): Pagination offset
- `tx_hashes` (optional): Filter by transaction hashes
- `counterparties` (optional): Filter by counterparties

**Example:**
```
"Find transactions between January 1st and February 1st"
```

#### `explain_transaction`
Get detailed information about a specific transaction.

**Parameters:**
- `txhash` (required): Transaction hash

**Example:**
```
"Explain transaction 0x123..."
```

### Analytics

#### `counterparty_summary`
View aggregated activity by counterparty.

**Parameters:**
- `from_ts_ms` (optional): Start timestamp
- `to_ts_ms` (optional): End timestamp
- `top_n` (optional): Return top N counterparties (1-100)

**Example:**
```
"Show me my top counterparties"
```

## Resources

### `rotki://user/summary`
Portfolio summary resource with totals, allocation, and recent PnL.

**Format:** application/json

## Prompts

### `summarize_portfolio`
Guided prompt to analyze portfolio risk and allocations.

**Parameters:**
- `horizon` (optional): Time horizon (e.g., "30d", "90d", "1y")

## Development

```bash
# Run in development mode
pnpm dev

# Build for production
pnpm build

# Type check
pnpm typecheck
```

## Testing

### Manual stdio Testing

```bash
# Test initialize
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node dist/server.js

# Test tool call
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_prices","arguments":{"assets":["BTC","ETH"]}}}' | node dist/server.js
```

### Using the Test Scripts

```bash
# SDK-based test
pnpm exec tsx scripts/test-stdio.ts

# Bash-based test
./scripts/test-stdio-bash.sh
```

## Architecture

### Design Philosophy

This server follows a **jobs-to-be-done** approach, providing high-level tools that abstract Rotki's REST API complexity:

- Single tools compose multiple API calls when needed
- Clear input validation with descriptive error messages
- Consistent response formats
- Proper error handling with `isError` flags

### File Structure

```
mcp-rotki/
├── src/
│   ├── server.ts       # MCP server with tool/resource registration
│   ├── rotki.ts        # Thin REST client for Rotki API
│   └── types.ts        # TypeScript type definitions
├── scripts/
│   ├── test-stdio.ts          # SDK-based test
│   └── test-stdio-bash.sh     # Bash-based test
├── dist/               # Compiled output
├── package.json
├── tsconfig.json
└── README.md
```

## Security

- **Never commit secrets**: Use environment variables for credentials
- **Read-only by default**: Server only queries data, no modifications
- **Local-first**: Designed for local Rotki instances
- **Validated inputs**: All parameters validated with Zod schemas

## Troubleshooting

### Server not appearing in Claude

1. **Check config path**: Ensure the path to `dist/server.js` is absolute
2. **Restart Claude**: Configuration is only loaded on startup
3. **Check logs**: Look for MCP connection errors in Claude's logs
4. **Verify build**: Run `pnpm build` to ensure server is compiled

### Rotki connection errors

1. **Is Rotki running?** Check `http://127.0.0.1:4242/api/1/ping`
2. **Is Rotki unlocked?** Some endpoints require authentication
3. **Check base URL**: Verify `ROTKI_MCP_BASE_URL` environment variable
4. **Check timeout**: Increase `ROTKI_MCP_TIMEOUT_MS` if needed

### Tool validation errors

All tools use strict Zod validation. Common issues:

- **Empty arrays**: Some parameters require at least 1 item (e.g., `assets`)
- **Missing required fields**: Check the tool's `inputSchema` for required parameters
- **Invalid ranges**: Some numbers have min/max constraints (e.g., `window_days: 1-365`)

## Roadmap

- [ ] Add WebSocket support for real-time updates
- [ ] Implement resource subscriptions
- [ ] Add more advanced DeFi protocol integrations
- [ ] Support for historical PnL calculations
- [ ] Multi-user support

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

## License

MIT License - See LICENSE file for details

## Related Projects

- [Rotki](https://rotki.com/) - Open source portfolio tracker
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification
- [Claude Desktop](https://claude.ai/) - AI assistant with MCP support

## Support

- **Issues**: [GitHub Issues](https://github.com/dennisonbertram/mcp-rotki/issues)
- **Rotki Docs**: [rotki.readthedocs.io](https://rotki.readthedocs.io/)
- **MCP Docs**: [modelcontextprotocol.io](https://modelcontextprotocol.io/)

---

**Built with ❤️ for the Rotki and MCP communities**