crypto-transactions-mcp

MCP server per tracciare transazioni e ordini eseguiti nel mercato crypto. Espone tool MCP che permettono a un agent LLM (Claude, agy, ecc.) di registrare trade, swap e trasferimenti con precisione Decimal esatta, e di interrogare lo storico — con persistenza intercambiabile su un file JSON locale o su un database Notion.

Quick Start

1. uv sync per installare le dipendenze.

2. Scegli un backend:

   • JSON (default, zero config) — salta al punto 3.

   • Notion — segui prima la sezione "Setup Notion da zero" qui sotto.

3. Aggiungi il server alla configurazione del tuo host MCP: vedi "Configurazione Claude Desktop" o "Configurazione agy".

4. Riavvia l'host e prova, ad esempio: "Ho comprato 0.1 BTC su Binance a 65000 USDT, fee 0.0001 BTC, registralo con log_transaction."

Architettura onion:

• domain/ — entità CryptoTransaction (Pydantic v2, campi monetari in Decimal). side è BUY/SELL (trade, incluso uno swap crypto/crypto) oppure TRANSFER (spostamento dello stesso asset tra due custodie); i due casi hanno requisiti diversi validati nel modello stesso (BUY/SELL richiedono price/value, TRANSFER richiede to_exchange)

• interfaces/ — port TransactionRepository e TransactionFilters

• usecases/ — LogTransactionUseCase (trade, upsert con merge parziale), LogTransferUseCase (transfer, stessa semantica di upsert), GetTransactionHistoryUseCase

• infrastructure/ — adapter concreti del port TransactionRepository:

  • JsonTransactionRepository, file JSON locale, path fisso data/crypto_transactions.json

  • NotionTransactionRepository, database Notion (vedi sotto)

• delivery/ — server FastMCP, tool MCP (log_transaction, log_transfer, get_transaction_history), wiring delle dipendenze in factories.py

Related MCP server: Expense Tracker MCP Server

Tool MCP

• log_transaction — trade BUY/SELL, incluso uno swap tra due crypto (es. ETH/BTC): stessa forma di un trade normale, non serve un tool a parte. Supporta fiat_value/fiat_currency opzionali per fissare il controvalore fiat al momento dello scambio — fortemente consigliato per gli swap crypto/crypto, dove il solo price (cambio relativo tra le due crypto) non permette di calcolare a posteriori il P&L realizzato né il cost-basis fiat del nuovo asset ricevuto.

• log_transfer — spostamento dello stesso asset tra due custodie (exchange → to_exchange), non un trade: niente side/price, ma richiede to_exchange.

• get_transaction_history — storico di entrambi, con filtri opzionali (symbol, exchange, side incluso "TRANSFER", date_from/date_to).

Setup

uv sync

Copia .env.example in .env e valorizzalo: viene caricato automaticamente all'avvio (main.py chiama load_dotenv()). Questo funziona anche quando il server è lanciato da un host esterno (Claude Desktop, agy, ...) con uv run --directory <path> main.py, perché --directory imposta la working directory del processo sulla root del progetto, dove load_dotenv() cerca .env di default — non serve duplicare i secret nel JSON di config dell'host, che spesso è meno protetto di un .env locale gitignored.

Backend di persistenza

Selezionabile con la variabile d'ambiente TRANSACTION_REPOSITORY_BACKEND:

• json (default) — nessuna configurazione aggiuntiva richiesta.

• notion — richiede NOTION_TOKEN (token dell'integration Notion) e NOTION_DATABASE_ID.

Setup Notion da zero

Se non hai già un'integration Notion collegata a questo progetto, segui questi passi in ordine (richiede un account Notion con permessi di creare integration nel workspace):

1. Crea l'integration — vai su notion.so/my-integrations → "+ New integration" → dai un nome (es. "Crypto Transactions MCP") → scegli il workspace → tipo "Internal".

2. Abilita le capabilities — nella pagina di configurazione dell'integration, sotto "Capabilities", abilita: Read content, Update content, Insert content.

3. Copia il token — tab "Secrets" → copia il valore di "Internal Integration Secret" (inizia con secret_ o ntn_). Questo è il tuo NOTION_TOKEN.

4. Crea il database — in Notion, crea un nuovo database (full-page o inline) e configuralo con esattamente le property elencate nella tabella sotto. La colonna "title" che Notion crea di default (di solito "Name") va rinominata in Transaction ID: ogni database Notion ne ha obbligatoriamente una, non è il nome del database ma la colonna che identifica ogni riga.

5. Condividi il database con l'integration — apri la pagina del database → menu "..." in alto a destra → "Connections" → cerca e collega l'integration creata al punto 1. Senza questo passaggio l'API risponde 404 anche con un token valido, perché i permessi Notion sono per-pagina, non workspace-wide.

6. Trova il database ID — è nell'URL della pagina del database: https://www.notion.so/<ID-senza-trattini>?v=.... Ad esempio, da https://www.notion.so/abcdef0123456789abcdef0123456789?v=... l'ID è abcdef0123456789abcdef0123456789. Questo è il tuo NOTION_DATABASE_ID.

7. Configura le variabili — nel tuo .env (vedi sopra), o nel blocco env dell'host MCP:

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

Il database Notion deve avere queste property (nome esatto e tipo):

To Exchange, Price, Value, Fiat Value, Fiat Currency possono essere vuoti (non si applicano a un TRANSFER, o sono opzionali su un trade).

Nota: i campi numerici su Notion sono number nativi (float64), non Decimal esatti come nel backend JSON — sufficiente per gli importi reali di trading, ma soggetto ai limiti di precisione di un float a doppia precisione.

Test

uv run pytest

Esecuzione manuale

uv run main.py

Configurazione Claude Desktop

Aggiungi al file claude_desktop_config.json (su macOS: ~/Library/Application Support/Claude/claude_desktop_config.json). Con un .env già configurato alla root del progetto (vedi sopra) basta questo, nessun secret nel JSON:

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

In alternativa, se preferisci non usare un file .env, puoi passare le variabili direttamente nel blocco env (sovrascrivono quelle di .env se presenti entrambe):

{
  "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"
      }
    }
  }
}

Configurazione agy

Stesso schema mcpServers, ma nel file .agents/mcp_config.json alla root del progetto in cui usi agy (aggiungi la voce crypto-transactions accanto agli altri server già presenti, senza rimuoverli). Vale la stessa cosa: con .env configurato non serve il blocco env:

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