cointracking-mcp

An MCP (Model Context Protocol) server that exposes the CoinTracking API as tools for Claude Desktop, Cowork, and any other MCP-compatible client.

It gives Claude direct, read-only access to your full crypto history (trades, deposits, withdrawals, staking, DeFi, airdrops, mining, etc.) so you can do portfolio analysis, reporting, and tax planning by simply asking.

Disclaimer

This is an unofficial, independent project. It is not affiliated with, authorized by, endorsed by, or connected to CoinTracking (CoinTracking GmbH) in any way. The name "CoinTracking" is used only descriptively, to identify the API this connector integrates with (nominative use); no logos or trademarks are included.

Use of the CoinTracking API through this connector is subject to CoinTracking's own terms of service and remains the sole responsibility of each user. The software is provided "as is" under the MIT License, without warranty of any kind.

Tools

All tools are read-only (readOnlyHint: true) and prefixed with cointracking_:

Installation

git clone https://github.com/alemuenchen/cointracking-mcp.git
cd cointracking-mcp
npm install
npm run build

Get your CoinTracking API credentials

1. Log in to CoinTracking.
2. Go to Account → API.
3. Create a new API key. Read-only is enough — this server never writes.
4. Copy the API Key and API Secret.

Configuration

The server reads two credentials from the environment: COINTRACKING_API_KEY and COINTRACKING_API_SECRET. The run.sh wrapper resolves them from three sources, in priority order:

1. Environment variables already set — e.g. passed through your MCP client config.
2. The macOS Keychain — run ./setup-keychain.sh once to store them; it prompts invisibly and writes nothing to disk.
3. A .env file in the connector directory — copy .env.example to .env and fill it in.

Pick whichever fits your platform. The Keychain option is the most secure on macOS; the .env file is the portable fallback.

Claude Desktop / Cowork configuration

Add this to your claude_desktop_config.json. Using the run.sh wrapper lets it resolve credentials from the Keychain or .env automatically:

{
  "mcpServers": {
    "cointracking": {
      "command": "/absolute/path/to/cointracking-mcp/run.sh"
    }
  }
}

Alternatively, call the built server directly and pass the credentials inline:

{
  "mcpServers": {
    "cointracking": {
      "command": "node",
      "args": ["/absolute/path/to/cointracking-mcp/dist/index.js"],
      "env": {
        "COINTRACKING_API_KEY": "your-api-key",
        "COINTRACKING_API_SECRET": "your-api-secret"
      }
    }
  }
}

Restart Claude Desktop and the cointracking_* tools will become available.

Test with MCP Inspector

COINTRACKING_API_KEY=... COINTRACKING_API_SECRET=... npm run inspect

This launches the official MCP Inspector against the built server so you can list and call tools interactively.

Tests

npm test

Vitest unit tests cover the nonce generator, the HMAC-SHA512 request signing, the coinTrackingRequest error handling (rate limit, HTTP errors, non-JSON bodies, API-level errors, network failures), and the Zod input schemas of every tool. The tests mock fetch, so they need no API credentials and make no network calls.

Notes & limits

• Rate limit: CoinTracking allows 60 calls/hour on Unlimited accounts. The server returns a clear error on HTTP 429 — wait, then narrow your queries.
• Timestamps: start and end are UNIX seconds, not milliseconds.
• Big histories: getTrades can return a lot of data. Always pass limit and start/end for large accounts.
• Nonce: the client uses Date.now() plus an in-process counter, so the nonce is strictly increasing even for back-to-back calls in the same millisecond.
• Auth: HMAC-SHA512 of the URL-encoded body, signed with the API secret, sent in the Sign header alongside Key.

Contributing & security

Contributions are welcome — see CONTRIBUTING.md. To report a security issue, follow SECURITY.md (please do not open a public issue for vulnerabilities).

License

MIT © Alessandro Melazzini