crypto-transactions-mcp

MCP server for tracking transactions and orders executed in the crypto market. It exposes MCP tools that let an LLM agent (Claude, agy, etc.) record trades, swaps, and transfers with exact Decimal precision, and query the history — with swappable persistence on a local JSON file or a Notion database.

Quick Start

1. uv sync to install dependencies.

2. Choose a backend:

   • JSON (default, zero config) — skip to step 3.

   • Notion — first follow the "Set up Notion from scratch" section below.

3. Add the server to your MCP host configuration: see "Claude Desktop configuration" or "agy configuration".

4. Restart the host and try, for example: "I bought 0.1 BTC on Binance at 65000 USDT, fee 0.0001 BTC, record it with log_transaction."

Onion architecture:

• domain/ — the CryptoTransaction entity (Pydantic v2, monetary fields in Decimal). side is BUY/SELL (trade, including a crypto/crypto swap) or TRANSFER (moving the same asset between two custodial accounts); the two cases have different requirements validated in the model itself (BUY/SELL require price/value, TRANSFER requires to_exchange)

• interfaces/ — the TransactionRepository and TransactionFilters ports

• usecases/ — LogTransactionUseCase (trade, upsert with partial merge), LogTransferUseCase (transfer, same upsert semantics), GetTransactionHistoryUseCase

• infrastructure/ — concrete adapters of the TransactionRepository port:

  • JsonTransactionRepository, local JSON file, fixed path data/crypto_transactions.json

  • NotionTransactionRepository, Notion database (see below)

• delivery/ — the FastMCP server, MCP tools (log_transaction, log_transfer, get_transaction_history), dependency wiring in factories.py

Related MCP server: Expense Tracker MCP Server

MCP tools

• log_transaction — BUY/SELL trade, including a swap between two cryptos (e.g. ETH/BTC): same shape as a normal trade, no separate tool needed. Supports optional fiat_value/fiat_currency to lock in the fiat equivalent at the time of the exchange — strongly recommended for crypto/crypto swaps, where price alone (the relative exchange rate between the two cryptos) does not allow you to calculate the realized P&L afterwards, nor the fiat cost basis of the new asset received.

• log_transfer — moving the same asset between two custodial accounts (exchange → to_exchange), not a trade: no side/price, but requires to_exchange.

• get_transaction_history — history of both, with optional filters (symbol, exchange, side including "TRANSFER", date_from/date_to), sorted by date descending (most recent first) and paginated (limit default 50, offset); the response is {"transactions": [...], "has_more": bool}.

• get_portfolio_summary — for each asset (excluding vs_currency itself): how much you own, how much you invested in total and on average per unit (cost basis), market value, unrealized gain/loss. Optional as_of_date for a position as of a past date (historical price) instead of live — designed for tax reporting. cost_basis_method (weighted_average or fifo) is an explicit choice, not automatic: they can produce different capital gains on the same history, check with an accountant which one you need.

• get_asset_price — quote for a single asset, current or historical as of a date, without computing the whole portfolio.

Setup

uv sync

Copy .env.example to .env and fill it in: it is loaded automatically at startup (main.py calls load_dotenv()). This works even when the server is launched by an external host (Claude Desktop, agy, ...) with uv run --directory <path> main.py, because --directory sets the process working directory to the project root, where load_dotenv() looks for .env by default — there is no need to duplicate secrets in the host config JSON, which is often less protected than a local gitignored .env.

Persistence backend

Selectable with the TRANSACTION_REPOSITORY_BACKEND environment variable:

• json (default) — no additional configuration required.

• notion — requires NOTION_TOKEN (Notion integration token) and NOTION_DATABASE_ID.

Set up Notion from scratch

If you don't already have a Notion integration connected to this project, follow these steps in order (requires a Notion account with permission to create integrations in the workspace):

1. Create the integration — go to notion.so/my-integrations → "+ New integration" → give it a name (e.g. "Crypto Transactions MCP") → choose the workspace → type "Internal".

2. Enable the capabilities — on the integration configuration page, under "Capabilities", enable: Read content, Update content, Insert content.

3. Copy the token — "Secrets" tab → copy the value of "Internal Integration Secret" (starts with secret_ or ntn_). This is your NOTION_TOKEN.

4. Create the database — in Notion, create a new database (full-page or inline) and configure it with exactly the properties listed in the table below. The "title" column that Notion creates by default (usually "Name") must be renamed to Transaction ID: every Notion database is required to have one; it is not the database name but the column that identifies each row.

5. Share the database with the integration — open the database page → "..." menu at the top right → "Connections" → search for and connect the integration created in step 1. Without this step the API returns 404 even with a valid token, because Notion permissions are per-page, not workspace-wide.

6. Find the database ID — it is in the database page URL: https://www.notion.so/<ID-senza-trattini>?v=.... For example, from https://www.notion.so/abcdef0123456789abcdef0123456789?v=... the ID is abcdef0123456789abcdef0123456789. This is your NOTION_DATABASE_ID.

7. Configure the variables — in your .env (see above), or in the host MCP env block:

   TRANSACTION_REPOSITORY_BACKEND=notion
   NOTION_TOKEN=<il secret del punto 3>
   NOTION_DATABASE_ID=<l'id del punto 6>

The Notion database must have these properties (exact name and type):

To Exchange, Price, Value, Fiat Value, Fiat Currency can be empty (they don't apply to a TRANSFER, or they are optional on a trade).

Note: numeric fields on Notion are native number (float64), not exact Decimal like in the JSON backend — sufficient for real trading amounts, but subject to the precision limits of a double-precision float.

Tests

uv run pytest

Manual execution

uv run main.py

Claude Desktop configuration

Add to the claude_desktop_config.json file (on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json). With an .env already configured at the project root (see above), that's all you need, no secrets in the JSON:

{
  "mcpServers": {
    "crypto-transactions": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/crypto-transactions-mcp",
        "main.py"
      ]
    }
  }
}

Alternatively, if you prefer not to use a .env file, you can pass the variables directly in the env block (they override those in .env if both are present):

{
  "mcpServers": {
    "crypto-transactions": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/crypto-transactions-mcp",
        "main.py"
      ],
      "env": {
        "TRANSACTION_REPOSITORY_BACKEND": "notion",
        "NOTION_TOKEN": "secret_...",
        "NOTION_DATABASE_ID": "abcdef0123456789abcdef0123456789"
      }
    }
  }
}

agy configuration

Same mcpServers schema, but in the .agents/mcp_config.json file at the project root where you use agy (add the crypto-transactions entry next to the other servers already present, without removing them). The same applies: with .env configured you don't need the env block:

{
  "mcpServers": {
    "crypto-transactions": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/crypto-transactions-mcp",
        "main.py"
      ]
    }
  }
}