mcp-rotki by dennisonbertram - MCP Server

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

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:

Replace /absolute/path/to/mcp-rotki with your actual path
Restart Claude Desktop/Code after updating the config
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

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

Rotki connection errors

Is Rotki running? Check http://127.0.0.1:4242/api/1/ping
Is Rotki unlocked? Some endpoints require authentication
Check base URL: Verify ROTKI_MCP_BASE_URL environment variable
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:

Fork the repository
Create a feature branch
Make your changes with tests
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