Rotki Server

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

Author

Dennison Bertram (@dennisonbertram) Email: [email protected]

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 instance (default: http://127.0.0.1:4242)

Installation

# 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

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

# Run in development mode
pnpm dev

# Build for production
pnpm build

# Type check
pnpm typecheck

Testing

Manual stdio Testing

# 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

# 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 - Open source portfolio tracker
• Model Context Protocol - MCP specification
• Claude Desktop - AI assistant with MCP support

Support

• Issues: GitHub Issues
• Rotki Docs: rotki.readthedocs.io
• MCP Docs: modelcontextprotocol.io

---

Built with ❤️ for the Rotki and MCP communities