de en es it ja ko ru zh

crypto-transactions-mcp

Name: crypto-transactions-mcp
Author: bolesk

by bolesk

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

crypto-transactions-mcp

Servidor MCP para rastrear transacciones y órdenes ejecutadas en el mercado de criptomonedas. Expone herramientas MCP que permiten a un agente LLM (Claude, agy, etc.) registrar trades, swaps y transferencias con precisión Decimal exacta, y consultar el historial — con persistencia intercambiable en un archivo JSON local o en una base de datos de Notion.

Inicio rápido

uv sync para instalar las dependencias.
Elige un backend:
- JSON (por defecto, cero configuración) — salta al punto 3.
- Notion — sigue primero la sección "Configuración de Notion desde cero" más abajo.
Añade el servidor a la configuración de tu host MCP: consulta "Configuración de Claude Desktop" o "Configuración de agy".
Reinicia el host y prueba, por ejemplo: "He comprado 0.1 BTC en Binance a 65000 USDT, comisión 0.0001 BTC, regístralo con log_transaction."

Arquitectura en capas (onion):

domain/ — entidad CryptoTransaction (Pydantic v2, campos monetarios en Decimal). side es BUY/SELL (trade, incluido un swap crypto/crypto) o TRANSFER (movimiento del mismo activo entre dos custodias); los dos casos tienen requisitos diferentes validados en el propio modelo (BUY/SELL requieren price/value, TRANSFER requiere to_exchange)
interfaces/ — puerto TransactionRepository y TransactionFilters
usecases/ — LogTransactionUseCase (trade, upsert con fusión parcial), LogTransferUseCase (transferencia, misma semántica de upsert), GetTransactionHistoryUseCase
infrastructure/ — adaptadores concretos del puerto TransactionRepository:
- JsonTransactionRepository, archivo JSON local, ruta fija data/crypto_transactions.json
- NotionTransactionRepository, base de datos de Notion (ver más abajo)
delivery/ — servidor FastMCP, herramientas MCP (log_transaction, log_transfer, get_transaction_history), cableado de dependencias en factories.py

Related MCP server: Expense Tracker MCP Server

Herramientas MCP

log_transaction — trade BUY/SELL, incluido un swap entre dos criptomonedas (ej. ETH/BTC): misma forma que un trade normal, no se necesita una herramienta aparte. Admite fiat_value/fiat_currency opcionales para fijar el contravalor en fiat en el momento del intercambio — muy recomendado para swaps crypto/crypto, donde solo el price (tipo de cambio relativo entre las dos criptomonedas) no permite calcular a posteriori el P&L realizado ni el cost-basis en fiat del nuevo activo recibido.
log_transfer — movimiento del mismo activo entre dos custodias (exchange → to_exchange), no un trade: sin side/price, pero requiere to_exchange.
get_transaction_history — historial de ambos, con filtros opcionales (symbol, exchange, side incluido "TRANSFER", date_from/date_to), ordenado por fecha descendente (las más recientes primero) y paginado (limit por defecto 50, offset); la respuesta es {"transactions": [...], "has_more": bool}.
get_portfolio_summary — para cada activo (excluido el propio vs_currency): cuánto posees, cuánto has invertido en total y en promedio por unidad (cost-basis), valor de mercado, plusvalía/minusvalía no realizada. as_of_date opcional para una situación en una fecha pasada (precio histórico) en lugar de en vivo — pensado para la declaración fiscal. cost_basis_method (weighted_average o fifo) es una elección explícita, no automática: pueden dar plusvalías diferentes sobre el mismo historial, verifica cuál necesitas con un asesor fiscal.
get_asset_price — cotización de un solo activo, actual o histórica en una fecha, sin calcular todo el portafolio.

Configuración

uv sync

Copia .env.example a .env y complétalo: se carga automáticamente al inicio (main.py llama a load_dotenv()). Esto funciona también cuando el servidor se lanza desde un host externo (Claude Desktop, agy, ...) con uv run --directory <path> main.py, porque --directory establece el directorio de trabajo del proceso en la raíz del proyecto, donde load_dotenv() busca .env por defecto — no es necesario duplicar los secretos en el JSON de configuración del host, que a menudo está menos protegido que un .env local ignorado por git.

Backend de persistencia

Seleccionable con la variable de entorno TRANSACTION_REPOSITORY_BACKEND:

json (por defecto) — no requiere configuración adicional.
notion — requiere NOTION_TOKEN (token de la integración de Notion) y NOTION_DATABASE_ID.

Configuración de Notion desde cero

Si aún no tienes una integración de Notion vinculada a este proyecto, sigue estos pasos en orden (requiere una cuenta de Notion con permisos para crear integraciones en el workspace):

Crea la integración — ve a notion.so/my-integrations → "+ New integration" → ponle un nombre (ej. "Crypto Transactions MCP") → elige el workspace → tipo "Internal".
Habilita las capacidades — en la página de configuración de la integración, bajo "Capabilities", habilita: Read content, Update content, Insert content.
Copia el token — pestaña "Secrets" → copia el valor de "Internal Integration Secret" (empieza con secret_ o ntn_). Este es tu NOTION_TOKEN.
Crea la base de datos — en Notion, crea una nueva base de datos (de página completa o en línea) y configúrala exactamente con las propiedades enumeradas en la tabla de abajo. La columna "title" que Notion crea por defecto (normalmente "Name") debe renombrarse a Transaction ID: cada base de datos de Notion tiene obligatoriamente una, no es el nombre de la base de datos sino la columna que identifica cada fila.
Comparte la base de datos con la integración — abre la página de la base de datos → menú "..." en la parte superior derecha → "Connections" → busca y conecta la integración creada en el punto 1. Sin este paso la API responde 404 incluso con un token válido, porque los permisos de Notion son por página, no a nivel de workspace.
Encuentra el ID de la base de datos — está en la URL de la página de la base de datos: https://www.notion.so/<ID-sin-guiones>?v=.... Por ejemplo, de https://www.notion.so/abcdef0123456789abcdef0123456789?v=... el ID es abcdef0123456789abcdef0123456789. Este es tu NOTION_DATABASE_ID.

Configura las variables — en tu .env (ver arriba), o en el bloque env del host MCP:

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

La base de datos de Notion debe tener estas propiedades (nombre exacto y tipo):

Propiedad	Tipo
`Transaction ID`	title
`Tx Hash`	rich_text
`Exchange`	select
`To Exchange`	select
`Symbol`	select
`Side`	select (`BUY`, `SELL`, `TRANSFER`)
`Timestamp`	date (con hora, UTC)
`Amount`	number
`Price`	number
`Value`	number
`Fee Amount`	number
`Fee Asset`	select
`Fiat Value`	number
`Fiat Currency`	select
`Notes`	rich_text

To Exchange, Price, Value, Fiat Value, Fiat Currency pueden estar vacías (no se aplican a un TRANSFER, o son opcionales en un trade).

Nota: los campos numéricos en Notion son number nativos (float64), no Decimal exactos como en el backend JSON — suficiente para los importes reales de trading, pero sujeto a los límites de precisión de un float de doble precisión.

Pruebas

uv run pytest

Ejecución manual

uv run main.py

Configuración de Claude Desktop

Añade al archivo claude_desktop_config.json (en macOS: ~/Library/Application Support/Claude/claude_desktop_config.json). Con un .env ya configurado en la raíz del proyecto (ver arriba) basta esto, ningún secreto en el JSON:

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

Alternativamente, si prefieres no usar un archivo .env, puedes pasar las variables directamente en el bloque env (sobrescriben las de .env si están presentes ambas):

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

Configuración de agy

Mismo esquema mcpServers, pero en el archivo .agents/mcp_config.json en la raíz del proyecto donde usas agy (añade la entrada crypto-transactions junto a los otros servidores ya presentes, sin eliminarlos). Vale lo mismo: con .env configurado no se necesita el bloque env:

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

Available Tools

3 tools

get_transaction_historyA

Restituisce lo storico delle transazioni salvate (trade e transfer), filtrato opzionalmente per symbol, exchange, side (usa "TRANSFER" per i soli transfer) e/o intervallo di date (date_from/date_to, inclusivi, in UTC).

ParametersJSON Schema

Name	Required	Description	Default
`side`	No
`symbol`	No
`date_to`	No
`exchange`	No
`date_from`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It states the action is read-only ('Restituisce') and specifies that date filters are inclusive and in UTC. However, it does not disclose other behavioral traits such as response format, pagination, or any side effects. The description is minimally adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is front-loaded with the main action and then details parameters. It is concise but could be restructured for easier scanning (e.g., bullet points). However, it contains no unnecessary words and effectively communicates the tool's purpose and filters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists (assumed but not shown), so explanation of return values is not required. The description covers filtering options and date inclusivity/UTC zone. However, it lacks information on default behavior (e.g., returns all history if no filters), pagination, or response limits. For a history retrieval tool, this is acceptable but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description adds meaningful context: it explains the side parameter can use 'TRANSFER' to filter only transfers, and notes that date filters are inclusive and in UTC. This adds semantic value beyond the schema's property names and types. It could further describe parameter formats or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns saved transaction history (trades and transfers) with optional filtering. The verb 'Restituisce' and resource 'storico delle transazioni' are specific. Sibling tools (log_transaction, log_transfer) are for creation, so the read purpose is distinguishable, though not explicitly contrasted.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implied usage: use when you need to retrieve transaction history. The description lists available filters but does not provide explicit guidance on when to use this tool versus siblings or when not to use it. No alternatives or exclusions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

log_transactionA

Registra un trade (BUY/SELL, incluso uno swap tra due crypto), upsert per id.

    Trade normale (es. BTC/USDT): symbol è la coppia BASE/QUOTE,
    side=BUY se acquisti il base, side=SELL se lo cedi; price è il
    prezzo unitario del base in quote.

    Swap crypto/crypto (es. scambio ETH -> BTC su un DEX o un exchange):
    si usa questo stesso tool, non ce n'è uno dedicato. Metti come base
    l'asset ceduto e come quote quello ricevuto, es. symbol="ETH/BTC",
    side="SELL", amount=1 (ETH ceduti), price=0.05 (BTC ricevuti per
    ETH). Attenzione: in questo caso price ti dice solo il cambio tra
    le due crypto, non il loro controvalore in una valuta fiat — senza
    quel dato non potrai più calcolare a posteriori né il P&L realizzato
    sull'asset ceduto né il cost-basis fiat del nuovo asset ricevuto.
    Per questo, quando disponibile, valorizza sempre fiat_value (il
    controvalore totale dello scambio, es. in EUR al momento
    dell'esecuzione) e fiat_currency: è fortemente consigliato per gli
    swap crypto/crypto, utile anche per i trade con quote fiat/stablecoin.

    Se `id` è omesso viene generata una nuova transazione con un id
    generato automaticamente. Se `id` corrisponde a una transazione già
    salvata, solo i campi passati vengono aggiornati (merge parziale);
    `value` viene ricalcolato come amount * price se non fornito
    esplicitamente e uno tra amount/price cambia. Per una nuova
    transazione sono richiesti tutti i campi obbligatori dello schema
    (exchange, symbol, side, timestamp, amount, price, fee_amount,
    fee_asset). `tx_hash` è opzionale, usalo per l'hash on-chain quando
    disponibile (tipico per gli swap su DEX).

    Per spostare lo stesso asset tra due exchange/wallet, senza
    scambiarlo con un altro asset, usa invece il tool log_transfer.

ParametersJSON Schema

Name	Required	Description	Default
`id`	No
`side`	No
`notes`	No
`price`	No
`value`	No
`amount`	No
`symbol`	No
`tx_hash`	No
`exchange`	No
`fee_asset`	No
`timestamp`	No
`fee_amount`	No
`fiat_value`	No
`fiat_currency`	No

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses key behavioral traits: upsert behavior (merge partial update when id matches), auto-generation of id for new transactions, recalculation of value based on amount*price, required fields for new transactions, and the optional use of tx_hash. No annotations are provided, so the description fully compensates.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is relatively long but well-structured with paragraphs separating normal trades, swaps, upsert behavior, and required fields. It is front-loaded with the main purpose. However, some content could be condensed, making it less concise than optimal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (14 parameters, upsert behavior, swap handling) and the absence of an output schema, the description covers most behavioral aspects thoroughly. It mentions sibling tools for disambiguation. It does not explain the return value of the tool, which is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description explains the meanings of several key parameters (side, symbol, price, amount, fiat_value, fiat_currency, id, tx_hash, value). It does not explicitly cover all 14 parameters (e.g., notes, timestamp, exchange, fee_amount, fee_asset are mentioned as required but not detailed). The coverage is extensive enough to guide an agent, though not exhaustive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly defines the tool as recording a trade (BUY/SELL, including swaps) and differentiates it from the sibling log_transfer tool, specifying which tool to use for asset transfers without exchange. The verb 'Registra' and the resource 'trade' are specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance on when to use this tool vs the sibling log_transfer: 'Per spostare lo stesso asset tra due exchange/wallet, senza scambiarlo con un altro asset, usa invece il tool log_transfer.' Also explains how to handle crypto/crypto swaps, including the recommendation to provide fiat_value and fiat_currency for better P&L calculation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

log_transferA

Registra il movimento dello stesso asset tra due custodie (exchange o wallet), upsert per id. Non è un trade: non c'è side né un prezzo di scambio, quindi non usare questo tool per uno swap tra due asset diversi (per quello usa log_transaction).

    `exchange` è l'origine, `to_exchange` la destinazione. `symbol` è
    il solo asset spostato (es. "BTC"), non una coppia. `fee_amount`/
    `fee_asset` rappresentano la fee di rete del trasferimento, non una
    commissione di trading. `tx_hash` è fortemente consigliato quando
    disponibile (tipico per i prelievi/depositi on-chain). `fiat_value`/
    `fiat_currency` sono opzionali, per tracciare il controvalore fiat
    dell'importo spostato al momento del trasferimento.

    Se `id` è omesso viene generato automaticamente. Se `id`
    corrisponde a un transfer già salvato, solo i campi passati vengono
    aggiornati (merge parziale). Per un nuovo transfer sono richiesti
    exchange, to_exchange, symbol, timestamp, amount, fee_amount,
    fee_asset.

ParametersJSON Schema

Name	Required	Description	Default
`id`	No
`notes`	No
`amount`	No
`symbol`	No
`tx_hash`	No
`exchange`	No
`fee_asset`	No
`timestamp`	No
`fee_amount`	No
`fiat_value`	No
`to_exchange`	No
`fiat_currency`	No

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It explains upsert behavior (auto-generated ID, partial merge for existing records), required fields for new transfers, and the nature of fees (network fee, not trading commission). However, it does not explicitly address side effects like idempotency or potential data loss, slightly reducing completeness.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and distinction, followed by parameter details and behavior. It is slightly verbose but every part adds value. No redundant sentences, but could be tightened slightly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 12 parameters, upsert behavior, and no output schema, the description covers most essential aspects: both usage scenarios, parameter meanings, create vs. update behavior, and required fields. It doesn't describe the return value, but that's minor. Overall, it provides sufficient context for an agent to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so description must compensate. It explains key parameters: exchange (origin), to_exchange (destination), symbol (single asset), fee_amount/fee_asset (network fee), tx_hash (recommended), fiat_value/fiat_currency (optional). However, the 'notes' parameter is not mentioned, and 'amount' is implied but not explicitly defined, leaving a minor gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool logs asset movement between two custodians, uses 'upsert per id', and distinguishes it from a trade by noting no side or price. It also names the sibling tool log_transaction for swaps between different assets, making the purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly says when to use (same-asset transfer between custodians) and when not to (different-asset swap, directing to log_transaction). It also advises using tx_hash for on-chain transfers, providing practical guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

3 tool updatesv0.1.0Jul 14, 2026
- First observedget_transaction_history
- First observedlog_transaction
- First observedlog_transfer

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored 2026-07-14 10:50 across 3 tools

Disambiguation5/5

Each tool has a distinct and clear purpose: one for querying history, one for logging trades/swaps, and one for logging asset transfers. There is no overlap in functionality.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with lowercase and underscores: get_transaction_history, log_transaction, log_transfer. This is predictable and easy to understand.

Tool Count4/5

With only 3 tools, the set is minimal but covers the core actions of reading and writing transactions and transfers. It feels slightly thin but is still well-scoped for a focused server.

Completeness4/5

The server covers basic CRUD operations for transactions and transfers, including upsert and filtering. Missing a dedicated tool for single transaction retrieval or deletion, but the existing tools can accommodate those needs.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

gainium-mcpOAuth
io.gainium
MCP server for Gainium — manage trading bots, deals, and balances via AI assistants
Cryptocurrency Finance
22
agentic-commerce A
io.bosonprotocol
MCP server for Boson Protocol — on-chain agentic commerce for physical & digital goods.
Blockchain E-commerce & Retail Autonomous Agents
632
StateyOAuth
ai.statey
An agent-native database over MCP: shared, validated, structured records in every AI chat.
Databases Knowledge & Memory
2
Relm CRM A
com.relmcrm
API-first CRM for LLMs - contacts, companies, deals and activities over a native MCP server.
CRM AI & Machine Learning
412

Related MCP Servers

seashailofficial
Blockchain Cryptocurrency Finance
seashail
A
license
Not graded
quality
D
maintenance
Agent-native, self-hosted MCP server for crypto trading and DeFi management. Enables agents to query balances, execute trades, and manage positions with a policy engine and secure key storage.
Updated 5 months ago (2026-04-29 05:55 UTC)
7
Apache 2.0
Expense Tracker MCP Server
Finance
Python-Blade
F
license
B
quality
D
maintenance
A powerful SQLite-backed expense tracking server built with the Model Context Protocol (MCP). This server allows AI agents (like Claude) to manage your personal finances by adding, deleting, and listing expenses directly from your chat interface.
Updated 8 months ago (2026-01-14 10:10 UTC)
3
-
bybit-trading
Cryptocurrency Finance Autonomous Agents
Vanszs
A
license
Not graded
quality
D
maintenance
MCP server for cryptocurrency trading across multiple exchanges (Bybit, Binance, KuCoin, etc.) with real-time price data, comparison, and natural language query support. Integrates with AI assistants via the Model Context Protocol.
Updated a year ago (2025-09-27 06:30 UTC)
MIT
ExpenseTracker MCP Server
Finance
axitmakwana45-cloud
F
license
Not graded
quality
B
maintenance
A lightweight MCP server that lets LLM clients track, query, and summarize personal expenses using a local SQLite database.
Updated 2 months ago (2026-07-17 06:50 UTC)
-

crypto-transactions-mcp

Inicio rápido

Herramientas MCP

Configuración

Backend de persistencia

Configuración de Notion desde cero

Pruebas

Ejecución manual

Configuración de Claude Desktop

Configuración de agy

Available Tools

Output Schema

TDQS

TDQS

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

seashailofficial

Expense Tracker MCP Server

bybit-trading

ExpenseTracker MCP Server