bitvavo-mcp

An MCP server that exposes a Bitvavo crypto exchange account as read-only tools for Claude (and other MCP clients).

⚠️ Read-only by design. The server only calls Bitvavo endpoints that view information — no trading, no withdrawals. Create your API key with the View information scope only.

What it does

Once connected, Claude can answer questions like:

• "What is my portfolio worth right now?"

• "How much XRP do I hold and what's my average cost basis?"

• "Show me my trade history on BTC-EUR."

• "What were my last 5 deposits and withdrawals?"

Tools

Install

You need Node.js 18 or later and a Bitvavo API key + secret with View information scope (create one).

Claude Desktop

Open your Claude Desktop config file:

Add an entry under mcpServers:

{
  "mcpServers": {
    "bitvavo": {
      "command": "npx",
      "args": ["-y", "bitvavo-mcp"],
      "env": {
        "BITVAVO_API_KEY": "your_api_key",
        "BITVAVO_API_SECRET": "your_api_secret"
      }
    }
  }
}

Restart Claude Desktop. The Bitvavo tools appear in the tools menu (hammer icon) of any new chat. npx -y downloads the latest published version on first run and caches it locally — no manual install step.

Claude Code

claude mcp add --scope user bitvavo \
  -e BITVAVO_API_KEY=your_api_key \
  -e BITVAVO_API_SECRET=your_api_secret \
  -- npx -y bitvavo-mcp

Use --scope local if you only want it active in the current project directory.

From source

If you want to hack on the code:

git clone https://github.com/aderik/bitvavo-mcp.git
cd bitvavo-mcp
npm install
npm run build
cp .env.example .env  # then fill in BITVAVO_API_KEY and BITVAVO_API_SECRET

Point Claude Desktop at the built file instead of npx:

{
  "mcpServers": {
    "bitvavo": {
      "command": "node",
      "args": ["/absolute/path/to/bitvavo-mcp/dist/server.js"]
    }
  }
}

The .env file is loaded relative to the running script, so credentials are found regardless of which directory Claude spawns the server from. .env is gitignored — never commit it.

Full transaction history via CSV import

Bitvavo's /trades and /orders REST endpoints expose only exchange (Advanced) trades. Transactions made via the Buy/Sell or Convert UI in the Bitvavo app use a separate brokerage backend and do not appear in the API. Staking distributions and rebates aren't in the API either.

To get the complete picture:

1. Download your transaction CSV from Bitvavo: Account → Transactiegeschiedenis → Exporteren → Volledige geschiedenis → format CSV.

2. In your Claude chat: "import_transactions van /pad/naar/Volledige geschiedenis.csv" — or call the tool directly.

3. Run get_pnl again — every traded asset (including fully sold-off positions) now shows its realized P&L, sourced from the imported records.

The data lives in ~/.bitvavo-mcp/transactions.db (override with BITVAVO_MCP_DATA_DIR=/some/path). Re-importing the same CSV is idempotent — rows are matched on Bitvavo's transaction_id.

Environment variables