Rotki MCP 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: dennison@dapphero.io

Related MCP server: finanze-mcp

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