Skip to main content
Glama

Crio MCP 🧊

Un servidor de Protocolo de Finalización de Modelos (MCP) para la herramienta de extracción de datos de blockchain Cryo .

Cryo MCP le permite acceder a las poderosas capacidades de extracción de datos de blockchain de Cryo a través de un servidor API que implementa el protocolo MCP, lo que facilita la consulta de datos de blockchain desde cualquier cliente compatible con MCP.

Para usuarios de LLM: Guía de flujo de trabajo de consultas SQL

Al utilizar este servidor MCP para ejecutar consultas SQL en datos de blockchain, siga este flujo de trabajo:

  1. Descargar datos con query_dataset :

    result = query_dataset(
        dataset="blocks",  # or "transactions", "logs", etc.
        blocks="15000000:15001000",  # or use blocks_from_latest=100
        output_format="parquet"  # important: use parquet for SQL
    )
    files = result.get("files", [])  # Get the returned file paths
  2. Explorar el esquema con get_sql_table_schema :

    # Check what columns are available in the file
    schema = get_sql_table_schema(files[0])
    # Now you can see all columns, data types, and sample data
  3. Ejecutar SQL con query_sql :

    # Option 1: Simple table reference (DuckDB will match the table name to file)
    sql_result = query_sql(
        query="SELECT block_number, timestamp, gas_used FROM blocks",
        files=files  # Pass the files from step 1
    )
    
    # Option 2: Using read_parquet() with explicit file path
    sql_result = query_sql(
        query=f"SELECT block_number, timestamp, gas_used FROM read_parquet('{files[0]}')",
        files=files  # Pass the files from step 1
    )

Alternativamente, utilice el enfoque combinado con query_blockchain_sql :

# Option 1: Simple table reference
result = query_blockchain_sql(
    sql_query="SELECT * FROM blocks",
    dataset="blocks",
    blocks_from_latest=100
)

# Option 2: Using read_parquet()
result = query_blockchain_sql(
    sql_query="SELECT * FROM read_parquet('/path/to/file.parquet')",  # Path doesn't matter
    dataset="blocks",
    blocks_from_latest=100
)

Para obtener un ejemplo completo y funcional, consulte examples/sql_workflow_example.py .

Related MCP server: EVM MCP Server

Características

  • Acceso completo al conjunto de datos criogénicos : consulte cualquier conjunto de datos criogénicos a través de un servidor API

  • Integración con MCP : funciona a la perfección con los clientes de MCP

  • Opciones de consulta flexibles : compatibilidad con todas las principales opciones de filtrado y salida de Cryo

  • Opciones de rango de bloques : consulta bloques específicos, el último bloque o rangos relativos

  • Filtrado de contratos : Filtrar datos por dirección del contrato

  • Acceso al último bloque : fácil acceso a los últimos datos del bloque de Ethereum

  • Múltiples formatos de salida : compatibilidad con JSON, CSV y Parquet

  • Información del esquema : obtenga esquemas de conjuntos de datos detallados y datos de muestra

  • Consultas SQL : ejecute consultas SQL directamente contra los datos de blockchain descargados

Instalación (opcional)

Esto no es necesario si va a ejecutar la herramienta con uvx directamente.

# install with UV (recommended)
uv tool install cryo-mcp

Requisitos

  • Python 3.8+

  • ultravioleta

  • Una instalación de Cryo en funcionamiento

  • Acceso a un punto final de Ethereum RPC

  • DuckDB (para la funcionalidad de consulta SQL)

Inicio rápido

Uso con Claude Code

  1. Ejecute claude mcp add para obtener un mensaje interactivo.

  2. Introduzca uvx como comando a ejecutar.

  3. Ingrese cryo-mcp --rpc-url <ETH_RPC_URL> [--data-dir <DATA_DIR>] como argumentos

  4. Como alternativa, proporcione ETH_RPC_URL y CRYO_DATA_DIR como variables de entorno.

Las nuevas instancias de claude ahora tendrán acceso a cryo según lo configurado para llegar a su punto final RPC y almacenar datos en el directorio especificado.

Herramientas disponibles

Cryo MCP expone las siguientes herramientas MCP:

list_datasets()

Devuelve una lista de todos los conjuntos de datos Cryo disponibles.

Ejemplo:

client.list_datasets()

query_dataset()

Consulta un conjunto de datos criogénicos con varias opciones de filtrado.

Parámetros:

  • dataset (str): el nombre del conjunto de datos a consultar (por ejemplo, 'bloques', 'transacciones', 'registros')

  • blocks (str, opcional): Especificación del rango de bloques (por ejemplo, '1000:1010')

  • start_block (int, opcional): Número de bloque de inicio (alternativa a bloques)

  • end_block (int, opcional): Número de bloque final (alternativa a bloques)

  • use_latest (bool, opcional): si es verdadero, consulta el último bloque

  • blocks_from_latest (int, opcional): Número de bloques desde el último a incluir

  • contract (str, opcional): Dirección del contrato por la que filtrar

  • output_format (str, opcional): Formato de salida ('json', 'csv', 'parquet')

  • include_columns (lista, opcional): columnas que se incluirán junto con los valores predeterminados

  • exclude_columns (lista, opcional): columnas para excluir de los valores predeterminados

Ejemplo:

# Get transactions from blocks 15M to 15.01M
client.query_dataset('transactions', blocks='15M:15.01M')

# Get logs for a specific contract from the latest 100 blocks
client.query_dataset('logs', blocks_from_latest=100, contract='0x1234...')

# Get just the latest block
client.query_dataset('blocks', use_latest=True)

lookup_dataset()

Obtenga información detallada sobre un conjunto de datos específico, incluido el esquema y los datos de muestra.

Parámetros:

  • name (str): El nombre del conjunto de datos a buscar

  • sample_start_block (int, opcional): bloque de inicio para datos de muestra

  • sample_end_block (int, opcional): Fin del bloque para datos de muestra

  • use_latest_sample (bool, opcional): utiliza el último bloque para la muestra

  • sample_blocks_from_latest (int, opcional): Número de bloques desde el último para la muestra

Ejemplo:

client.lookup_dataset('logs')

get_latest_ethereum_block()

Devuelve información sobre el último bloque de Ethereum.

Ejemplo:

client.get_latest_ethereum_block()

Herramientas de consulta SQL

Cryo MCP incluye varias herramientas para ejecutar consultas SQL en datos de blockchain:

query_sql()

Ejecute una consulta SQL contra los datos de blockchain descargados.

Parámetros:

  • query (str): consulta SQL a ejecutar

  • files (lista, opcional): Lista de rutas de archivos de Parquet para consultar. Si no hay ninguna, se usarán todos los archivos del directorio de datos.

  • include_schema (bool, opcional): si se debe incluir información del esquema en el resultado

Ejemplo:

# Run against all available files
client.query_sql("SELECT * FROM read_parquet('/path/to/blocks.parquet') LIMIT 10")

# Run against specific files
client.query_sql(
    "SELECT * FROM read_parquet('/path/to/blocks.parquet') LIMIT 10",
    files=['/path/to/blocks.parquet']
)

query_blockchain_sql()

Consulta datos de blockchain usando SQL y descarga automáticamente cualquier dato requerido.

Parámetros:

  • sql_query (str): consulta SQL a ejecutar

  • dataset (str, opcional): el conjunto de datos a consultar (por ejemplo, 'bloques', 'transacciones')

  • blocks (str, opcional): Especificación del rango de bloques

  • start_block (int, opcional): Número de bloque de inicio

  • end_block (int, opcional): Número de bloque final

  • use_latest (bool, opcional): si es verdadero, consulta el último bloque

  • blocks_from_latest (int, opcional): Número de bloques antes del último a incluir

  • contract (str, opcional): Dirección del contrato por la que filtrar

  • force_refresh (bool, opcional): fuerza la descarga de nuevos datos incluso si existen

  • include_schema (bool, opcional): incluye información del esquema en el resultado

Ejemplo:

# Automatically downloads blocks data if needed, then runs the SQL query
client.query_blockchain_sql(
    sql_query="SELECT block_number, gas_used, timestamp FROM blocks ORDER BY gas_used DESC LIMIT 10",
    dataset="blocks",
    blocks_from_latest=100
)

list_available_sql_tables()

Enumere todas las tablas disponibles que se pueden consultar con SQL.

Ejemplo:

client.list_available_sql_tables()

get_sql_table_schema()

Obtenga el esquema para un archivo parquet específico.

Parámetros:

  • file_path (str): Ruta al archivo parquet

Ejemplo:

client.get_sql_table_schema("/path/to/blocks.parquet")

get_sql_examples()

Obtenga ejemplos de consultas SQL para diferentes conjuntos de datos de blockchain.

Ejemplo:

client.get_sql_examples()

Opciones de configuración

Al iniciar el servidor Cryo MCP, puede utilizar estas opciones de línea de comandos:

  • --rpc-url URL : URL de RPC de Ethereum (anula la variable de entorno ETH_RPC_URL)

  • --data-dir PATH : Directorio para almacenar los datos descargados (anula la variable de entorno CRYO_DATA_DIR, el valor predeterminado es ~/.cryo-mcp/data/)

Variables de entorno

  • ETH_RPC_URL : URL de RPC de Ethereum predeterminada que se utilizará cuando no se especifique mediante la línea de comando

  • CRYO_DATA_DIR : Directorio predeterminado para almacenar los datos descargados cuando no se especifica mediante la línea de comando

Uso avanzado

Consultas SQL contra datos de blockchain

Cryo MCP le permite ejecutar potentes consultas SQL contra datos de blockchain, combinando la flexibilidad de SQL con las capacidades de extracción de datos de Cryo:

Flujo de consulta SQL de dos pasos

Puede dividir la extracción y consulta de datos en dos pasos separados:

# Step 1: Download data and get file paths
download_result = client.query_dataset(
    dataset="transactions",
    blocks_from_latest=1000,
    output_format="parquet"
)

# Step 2: Use the file paths to run SQL queries
file_paths = download_result.get("files", [])
client.query_sql(
    query=f"""
    SELECT 
        to_address as contract_address, 
        COUNT(*) as tx_count,
        SUM(gas_used) as total_gas,
        AVG(gas_used) as avg_gas
    FROM read_parquet('{file_paths[0]}')
    WHERE to_address IS NOT NULL
    GROUP BY to_address
    ORDER BY total_gas DESC
    LIMIT 20
    """,
    files=file_paths
)

Flujo de consulta SQL combinado

Para mayor comodidad, también puede utilizar la función combinada que maneja ambos pasos:

# Get top gas-consuming contracts
client.query_blockchain_sql(
    sql_query="""
    SELECT 
        to_address as contract_address, 
        COUNT(*) as tx_count,
        SUM(gas_used) as total_gas,
        AVG(gas_used) as avg_gas
    FROM read_parquet('/path/to/transactions.parquet')
    WHERE to_address IS NOT NULL
    GROUP BY to_address
    ORDER BY total_gas DESC
    LIMIT 20
    """,
    dataset="transactions",
    blocks_from_latest=1000
)

# Find blocks with the most transactions
client.query_blockchain_sql(
    sql_query="""
    SELECT 
        block_number, 
        COUNT(*) as tx_count
    FROM read_parquet('/path/to/transactions.parquet')
    GROUP BY block_number
    ORDER BY tx_count DESC
    LIMIT 10
    """,
    dataset="transactions",
    blocks="15M:16M"
)

# Analyze event logs by topic
client.query_blockchain_sql(
    sql_query="""
    SELECT 
        topic0, 
        COUNT(*) as event_count
    FROM read_parquet('/path/to/logs.parquet')
    GROUP BY topic0
    ORDER BY event_count DESC
    LIMIT 20
    """,
    dataset="logs",
    blocks_from_latest=100
)

Nota : Para consultas SQL, utilice siempre output_format="parquet" al descargar datos para garantizar un rendimiento óptimo con DuckDB. Al usar query_blockchain_sql , consulte las rutas de archivo directamente en su SQL mediante la función read_parquet() .

Consultas con rangos de bloques

Cryo MCP admite toda la sintaxis de especificación de bloques de Cryo:

# Using block numbers
client.query_dataset('transactions', blocks='15000000:15001000')

# Using K/M notation
client.query_dataset('logs', blocks='15M:15.01M')

# Using offsets from latest 
client.query_dataset('blocks', blocks_from_latest=100)

Filtrado de contratos

Filtrar registros y otros datos por dirección de contrato:

# Get all logs for USDC contract
client.query_dataset('logs', 
                    blocks='16M:16.1M', 
                    contract='0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48')

Selección de columnas

Incluya sólo las columnas que necesita:

# Get just block numbers and timestamps
client.query_dataset('blocks', 
                    blocks='16M:16.1M', 
                    include_columns=['number', 'timestamp'])

Desarrollo

Estructura del proyecto

cryo-mcp/
├── cryo_mcp/           # Main package directory
│   ├── __init__.py     # Package initialization
│   ├── server.py       # Main MCP server implementation
│   ├── sql.py          # SQL query functionality
├── tests/              # Test directory
│   ├── test_*.py       # Test files
├── pyproject.toml      # Project configuration
├── README.md           # Project documentation

Ejecutar pruebas

uv run pytest

Licencia

Instituto Tecnológico de Massachusetts (MIT)

Créditos

  • Construido sobre la increíble herramienta Cryo de Paradigm

  • Utiliza el protocolo MCP para la comunicación API

Available Tools

10 tools
get_latest_ethereum_blockB
Get information about the latest Ethereum block

Returns:
    Information about the latest block including block number

Inputs: no named parameters.

get_sql_examplesA
Get example SQL queries for different blockchain datasets with DuckDB

SQL WORKFLOW TIPS:
1. First download data: result = query_dataset('dataset_name', blocks='...', output_format='parquet')
2. Inspect schema: schema = get_sql_table_schema(result['files'][0])
3. Run SQL: query_sql("SELECT * FROM read_parquet('/path/to/file.parquet')", files=result['files'])

OR use the combined approach:
- query_blockchain_sql(sql_query="SELECT * FROM read_parquet('...')", dataset='blocks', blocks='...')

Returns:
    Dictionary of example queries categorized by dataset type and workflow patterns

Inputs: no named parameters.

get_sql_table_schemaA
Get the schema and sample data for a specific parquet file

WORKFLOW NOTE: Use this function to explore the structure of parquet files
before writing SQL queries against them. This will show you:
1. All available columns and their data types
2. Sample data from the file
3. Total row count

Usage example:
1. Get list of files: files = list_available_sql_tables()
2. For a specific file: schema = get_sql_table_schema(files[0]['path'])
3. Use columns in your SQL: query_sql("SELECT column1, column2 FROM read_parquet('/path/to/file.parquet')")

Args:
    file_path: Path to the parquet file (from list_available_sql_tables or query_dataset)
    
Returns:
    Table schema information including columns, data types, and sample data

Inputs: file_path (required).

get_transaction_by_hashC
Get detailed information about a transaction by its hash

Args:
    tx_hash: The transaction hash to look up
    
Returns:
    Detailed information about the transaction

Inputs: tx_hash (required).

list_available_sql_tablesA
List all available parquet files that can be queried with SQL

USAGE NOTES:
- This function lists parquet files that have already been downloaded
- Each file can be queried using read_parquet('/path/to/file.parquet') in your SQL
- For each file, this returns the file path, dataset type, and other metadata
- Use these file paths in your SQL queries with query_sql()

Returns:
    List of available files and their metadata

Inputs: no named parameters.

list_datasetsB

Return a list of all available cryo datasets

Inputs: no named parameters.

lookup_datasetA
Look up a specific dataset and return detailed information about it. IMPORTANT: Always use this
function before querying a new dataset to understand its required parameters and schema.

The returned information includes:
1. Required parameters for the dataset (IMPORTANT for datasets like 'balances' that need an address)
2. Schema details showing available columns and data types
3. Example queries for the dataset

When the dataset requires specific parameters like 'address' (for 'balances'),
ALWAYS use the 'contract' parameter in query_dataset() to pass these values.

Example:
For 'balances' dataset, lookup_dataset('balances') will show it requires an 'address' parameter.
You should then query it using:
query_dataset('balances', blocks='1000:1010', contract='0x1234...')

Args:
    name: The name of the dataset to look up
    sample_start_block: Optional start block for sample data (integer)
    sample_end_block: Optional end block for sample data (integer)
    use_latest_sample: If True, use the latest block for sample data
    sample_blocks_from_latest: Number of blocks before the latest to include in sample
    
Returns:
    Detailed information about the dataset including schema and available fields

Inputs: name (required), sample_blocks_from_latest, sample_end_block, sample_start_block, +1 more.

query_blockchain_sqlA
Download blockchain data and run SQL query in a single step

CONVENIENCE FUNCTION: This combines query_dataset and query_sql into one call.

You can write SQL queries using either approach:
1. Simple table references: "SELECT * FROM blocks LIMIT 10"
2. Explicit read_parquet: "SELECT * FROM read_parquet('/path/to/file.parquet') LIMIT 10"

DATASET-SPECIFIC PARAMETERS:
For datasets that require specific address parameters (like 'balances', 'erc20_transfers', etc.),
ALWAYS use the 'contract' parameter to pass ANY Ethereum address. For example:

- For 'balances' dataset: Use contract parameter for the address you want balances for
  query_blockchain_sql(
      sql_query="SELECT * FROM balances",
      dataset="balances",
      blocks='1000:1010',
      contract='0x123...'  # Address you want balances for
  )

Examples:
```
# Using simple table name
query_blockchain_sql(
    sql_query="SELECT * FROM blocks LIMIT 10",
    dataset="blocks",
    blocks_from_latest=100
)

# Using read_parquet() (the path will be automatically replaced)
query_blockchain_sql(
    sql_query="SELECT * FROM read_parquet('/any/path.parquet') LIMIT 10",
    dataset="blocks",
    blocks_from_latest=100
)
```

ALTERNATIVE WORKFLOW (more control):
If you need more control, you can separate the steps:
1. Download data: result = query_dataset('blocks', blocks_from_latest=100, output_format='parquet')
2. Inspect schema: schema = get_sql_table_schema(result['files'][0])
3. Run SQL query: query_sql("SELECT * FROM blocks", files=result['files'])

Args:
    sql_query: SQL query to execute - using table names or read_parquet()
    dataset: The specific dataset to query (e.g., 'transactions', 'logs', 'balances')
             If None, will be extracted from the SQL query
    blocks: Block range specification as a string (e.g., '1000:1010')
    start_block: Start block number (alternative to blocks)
    end_block: End block number (alternative to blocks)
    use_latest: If True, query the latest block
    blocks_from_latest: Number of blocks before the latest to include
    contract: Contract address to filter by - IMPORTANT: Use this parameter for ALL address-based filtering
      regardless of the parameter name in the native cryo command (address, contract, etc.)
    force_refresh: Force download of new data even if it exists
    include_schema: Include schema information in the result
    
Returns:
    SQL query results and metadata

Inputs: sql_query (required), blocks, blocks_from_latest, contract, +6 more.

query_datasetA
Download blockchain data and return the file paths where the data is stored.

IMPORTANT WORKFLOW NOTE: When running SQL queries, use this function first to download
data, then use the returned file paths with query_sql() to execute SQL on those files.

Example workflow for SQL:
1. First download data: result = query_dataset('transactions', blocks='1000:1010', output_format='parquet')
2. Get file paths: files = result.get('files', [])
3. Run SQL query: query_sql("SELECT * FROM read_parquet('/path/to/file.parquet')", files=files)

DATASET-SPECIFIC PARAMETERS:
For datasets that require specific address parameters (like 'balances', 'erc20_transfers', etc.),
ALWAYS use the 'contract' parameter to pass ANY Ethereum address. For example:

- For 'balances' dataset: Use contract parameter for the address you want balances for
  query_dataset('balances', blocks='1000:1010', contract='0x123...')

- For 'logs' or 'erc20_transfers': Use contract parameter for contract address
  query_dataset('logs', blocks='1000:1010', contract='0x123...')

To check what parameters a dataset requires, always use lookup_dataset() first:
lookup_dataset('balances')  # Will show required parameters

Args:
    dataset: The name of the dataset to query (e.g., 'logs', 'transactions', 'balances')
    blocks: Block range specification as a string (e.g., '1000:1010')
    start_block: Start block number as integer (alternative to blocks)
    end_block: End block number as integer (alternative to blocks)
    use_latest: If True, query the latest block
    blocks_from_latest: Number of blocks before the latest to include (e.g., 10 = latest-10 to latest)
    contract: Contract address to filter by - IMPORTANT: Use this parameter for ALL address-based filtering
      regardless of the parameter name in the native cryo command (address, contract, etc.)
    output_format: Output format (json, csv, parquet) - use 'parquet' for SQL queries
    include_columns: Columns to include alongside the defaults
    exclude_columns: Columns to exclude from the defaults

Returns:
    Dictionary containing file paths where the downloaded data is stored

Inputs: dataset (required), blocks, blocks_from_latest, contract, +6 more.

query_sqlA
Run a SQL query against downloaded blockchain data files

IMPORTANT WORKFLOW: This function should be used after calling query_dataset
to download data. Use the file paths returned by query_dataset as input to this function.

Workflow steps:
1. Download data: result = query_dataset('transactions', blocks='1000:1010', output_format='parquet')
2. Get file paths: files = result.get('files', [])
3. Execute SQL using either:
   - Direct table references: query_sql("SELECT * FROM transactions", files=files)
   - Or read_parquet(): query_sql("SELECT * FROM read_parquet('/path/to/file.parquet')", files=files)

To see the schema of a file, use get_sql_table_schema(file_path) before writing your query.

DuckDB supports both approaches:
1. Direct table references (simpler): "SELECT * FROM blocks"
2. read_parquet function (explicit): "SELECT * FROM read_parquet('/path/to/file.parquet')"

Args:
    query: SQL query to execute - can use simple table names or read_parquet()
    files: List of parquet file paths to query (typically from query_dataset results)
    include_schema: Whether to include schema information in the result
    
Returns:
    Query results and metadata

Inputs: query (required), files, include_schema.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 10 tools

    Disambiguation4/5

    Most tools have distinct purposes, but there is some overlap between query_blockchain_sql and the combination of query_dataset + query_sql. The descriptions clarify that query_blockchain_sql is a convenience function combining the two, which helps reduce confusion, but agents might still need to decide between the separate or combined approach.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with snake_case, such as get_latest_ethereum_block, list_available_sql_tables, and query_dataset. This consistency makes the tool set predictable and easy to navigate for agents.

    Tool Count5/5

    With 10 tools, the server is well-scoped for its purpose of blockchain data querying and SQL analysis. Each tool serves a clear role, from data retrieval (e.g., get_transaction_by_hash) to dataset exploration (e.g., lookup_dataset) and SQL execution (e.g., query_sql), without feeling bloated or sparse.

    Completeness5/5

    The tool set provides comprehensive coverage for blockchain data workflows, including data fetching (get_latest_ethereum_block, get_transaction_by_hash), dataset discovery (list_datasets, lookup_dataset), data download (query_dataset), SQL querying (query_sql, query_blockchain_sql), and schema inspection (get_sql_table_schema, list_available_sql_tables). There are no obvious gaps, and the tools support full CRUD-like operations for the domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers