Cryo MCP Server
低温 MCP 🧊
Cryo区块链数据提取工具的模型完成协议 (MCP) 服务器。
Cryo MCP 允许您通过实现 MCP 协议的 API 服务器访问 Cryo 强大的区块链数据提取功能,从而可以轻松地从任何兼容 MCP 的客户端查询区块链数据。
对于 LLM 用户:SQL 查询工作流指南
使用此 MCP 服务器对区块链数据运行 SQL 查询时,请遵循以下工作流程:
使用
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使用
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使用
query_sql运行 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 )
或者,使用与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
)有关完整的工作示例,请参阅examples/sql_workflow_example.py 。
Related MCP server: EVM MCP Server
特征
完整 Cryo 数据集访问:通过 API 服务器查询任何 Cryo 数据集
MCP 集成:与 MCP 客户端无缝协作
灵活的查询选项:支持所有主要的Cryo过滤和输出选项
区块范围选项:查询特定区块、最新区块或相对范围
合约过滤:按合约地址过滤数据
最新区块访问:轻松访问最新的以太坊区块数据
多种输出格式:JSON、CSV 和 Parquet 支持
架构信息:获取详细的数据集架构和示例数据
SQL 查询:直接针对下载的区块链数据运行 SQL 查询
安装(可选)
如果您直接使用uvx运行该工具,则不需要这样做。
# install with UV (recommended)
uv tool install cryo-mcp要求
Python 3.8+
紫外线
Cryo的工作安装
访问以太坊 RPC 端点
DuckDB(用于 SQL 查询功能)
快速入门
与 Claude Code 一起使用
运行
claude mcp add以获得交互式提示。输入
uvx作为运行命令。输入
cryo-mcp --rpc-url <ETH_RPC_URL> [--data-dir <DATA_DIR>]作为参数或者,提供
ETH_RPC_URL和CRYO_DATA_DIR作为环境变量。
claude的新实例现在可以访问 cryo,因为它配置为命中您的 RPC 端点并将数据存储在指定的目录中。
可用工具
Cryo MCP 公开了以下 MCP 工具:
list_datasets()
返回所有可用 Cryo 数据集的列表。
例子:
client.list_datasets()query_dataset()
使用各种过滤选项查询 Cryo 数据集。
参数:
dataset(str):要查询的数据集的名称(例如,“blocks”、“transactions”、“logs”)blocks(str,可选):块范围规范(例如,'1000:1010')start_block(int,可选):起始块号(块的替代)end_block(int,可选):结束块号(块的替代)use_latest(bool, 可选): 如果为 True,则查询最新区块blocks_from_latest(int,可选):从最新到包含的块数contract(str,可选):要过滤的合约地址output_format(str,可选):输出格式('json','csv','parquet')include_columns(列表,可选):与默认值一起包含的列exclude_columns(列表,可选):从默认值中排除的列
例子:
# 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()
获取有关特定数据集的详细信息,包括模式和示例数据。
参数:
name(str): 要查找的数据集的名称sample_start_block(int,可选):样本数据的起始块sample_end_block(int,可选):样本数据的结束块use_latest_sample(bool,可选):使用最新块作为样本sample_blocks_from_latest(int,可选):样本的最新块数
例子:
client.lookup_dataset('logs')get_latest_ethereum_block()
返回有关最新以太坊区块的信息。
例子:
client.get_latest_ethereum_block()SQL查询工具
Cryo MCP 包含几个用于针对区块链数据运行 SQL 查询的工具:
query_sql()
对下载的区块链数据运行 SQL 查询。
参数:
query(str):要执行的 SQL 查询files(列表,可选):要查询的 parquet 文件路径列表。如果为 None,则使用数据目录中的所有文件。include_schema(bool,可选):是否在结果中包含架构信息
例子:
# 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()
使用 SQL 查询区块链数据,自动下载任何所需数据。
参数:
sql_query(str): 要执行的 SQL 查询dataset(str,可选):要查询的数据集(例如,“区块”、“交易”)blocks(str,可选):块范围规范start_block(int,可选):起始块号end_block(int,可选):结束块号use_latest(bool, 可选): 如果为 True,则查询最新区块blocks_from_latest(int,可选):要包含的最新块之前块的数量contract(str,可选):要过滤的合约地址force_refresh(bool,可选):即使存在新数据也强制下载。include_schema(bool,可选):在结果中包含架构信息
例子:
# 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()
列出所有可用 SQL 查询的表。
例子:
client.list_available_sql_tables()get_sql_table_schema()
获取特定 parquet 文件的架构。
参数:
file_path(str): parquet 文件的路径
例子:
client.get_sql_table_schema("/path/to/blocks.parquet")get_sql_examples()
获取不同区块链数据集的示例 SQL 查询。
例子:
client.get_sql_examples()配置选项
启动 Cryo MCP 服务器时,您可以使用以下命令行选项:
--rpc-url URL:以太坊 RPC URL(覆盖 ETH_RPC_URL 环境变量)--data-dir PATH:存储下载数据的目录(覆盖 CRYO_DATA_DIR 环境变量,默认为 ~/.cryo-mcp/data/)
环境变量
ETH_RPC_URL:未通过命令行指定时使用的默认以太坊 RPC URLCRYO_DATA_DIR:未通过命令行指定时存储下载数据的默认目录
高级用法
针对区块链数据的 SQL 查询
Cryo MCP 允许您对区块链数据运行强大的 SQL 查询,将 SQL 的灵活性与 Cryo 的数据提取功能相结合:
两步 SQL 查询流程
您可以将数据提取和查询分为两个独立的步骤:
# 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
)组合 SQL 查询流
为了方便起见,您还可以使用处理这两个步骤的组合函数:
# 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
)注意:对于 SQL 查询,下载数据时请始终使用output_format="parquet"以确保 DuckDB 获得最佳性能。使用query_blockchain_sql时,应使用read_parquet()函数直接在 SQL 中引用文件路径。
使用块范围查询
Cryo MCP 支持 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)合同过滤
按合约地址过滤日志和其他数据:
# Get all logs for USDC contract
client.query_dataset('logs',
blocks='16M:16.1M',
contract='0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48')列选择
仅包含您需要的列:
# Get just block numbers and timestamps
client.query_dataset('blocks',
blocks='16M:16.1M',
include_columns=['number', 'timestamp'])发展
项目结构
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运行测试
uv run pytest
执照
麻省理工学院
致谢
Available Tools
10 toolsget_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
Scored across 10 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
Read-only MCP server for The Quiet Protocol's engines, benchmarks, proof, and business data.
MCP server connecting AI agents to non-custodial staking data across 130+ networks.
Token-free MCP server for structured RevoGrid Core, Pro, and Enterprise knowledge retrieval.
Related MCP Servers
- AlicenseDqualityDmaintenanceA Model Context Protocol server that gives LLMs the ability to interact with Ethereum networks, manage wallets, query blockchain data, and execute smart contract operations through a standardized interface.5414MIT
- AlicenseBqualityDmaintenanceA Model Context Protocol server that enables AI agents to interact with 30+ Ethereum-compatible blockchain networks, providing services like token transfers, contract interactions, and ENS resolution through a unified interface.2896 npm380MIT
- AlicenseBqualityDmaintenanceAn MCP server that provides access to Etherscan blockchain data APIs, allowing users to query Ethereum blockchain information through natural language.618MIT
- AlicenseNot gradedqualityBmaintenanceAn MCP server that bridges AI models with Ethereum blockchains via all JSON-RPC calls, enabling natural language queries for block numbers, balances, transactions, and smart contract data.21MIT