# blockscout-mcp-server [Health: Active] **Category:** 💻 Developer Tools **Repository:** https://github.com/blockscout/mcp-server **GitHub Stars:** 43 **npm Downloads (last month):** 125 **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/blockscout-mcp-server ## Description Provide AI agents and automation tools with contextual access to blockchain data including balance… ## Claude Desktop Quick Installation Remote MCP endpoint (confidence: high). Install path detected from listing signals. Add as a URL/SSE server in your client: ```json "mcpServers": { "blockscout-mcp-server": { "url": "https://smithery.ai/badge/@blockscout/mcp-server)](https://smithery.ai/server/@blockscout/mcp-server" } } ``` ## Documentation & README # Blockscout MCP Server [![smithery badge](https://smithery.ai/badge/@blockscout/mcp-server)](https://smithery.ai/server/@blockscout/mcp-server) Blockscout Server MCP server The Model Context Protocol (MCP) is an open protocol designed to allow AI agents, IDEs, and automation tools to consume, query, and analyze structured data through context-aware APIs. This server wraps Blockscout APIs and exposes blockchain data—balances, tokens, NFTs, contract metadata—via MCP so that AI agents and tools (like Claude, Cursor, or IDEs) can access and analyze it contextually. **Key Features:** - Contextual blockchain data access for AI tools - Multi-chain support via Blockscout PRO API configuration with Chainscout metadata enrichment - **Versioned REST API**: Provides a standard, web-friendly interface to all MCP tools. See [API.md](API.md) for full documentation. - Custom instructions for MCP host to use the server - Intelligent context optimization to conserve LLM tokens while preserving data accessibility - Smart response slicing with configurable page sizes to prevent context overflow - Opaque cursor pagination using Base64URL-encoded strings instead of complex parameters - Automatic truncation of large data fields with clear indicators and access guidance - Standardized ToolResponse model with structured JSON responses and follow-up instructions - Enhanced observability with MCP progress notifications and periodic updates for long-running operations ## Enhanced Analysis with Agent Skills For more powerful and efficient blockchain analysis, install the **Blockscout Analysis** skill from the [agent-skills repository](https://github.com/blockscout/agent-skills). This skill provides AI agents with structured guidance for execution strategies, response handling, security best practices, and workflow orchestration. **Learn more**: See the [agent-skills README](https://github.com/blockscout/agent-skills) for full capabilities and installation instructions. ## Configuring MCP Clients ### Blockscout PRO API Key Configuring the Blockscout MCP server with an AI agent requires a Blockscout PRO API key. Most of the data tools route their requests through the authenticated Blockscout PRO API gateway, so without a valid key those tools fail fast before making any upstream request. To obtain a key, register on the [Blockscout Developer Portal](https://dev.blockscout.com) (the free tier does not require a credit card) and generate an API key; keys are prefixed `proapi_`. Then supply it when configuring your client, as shown in the sections below. ### Using Claude Connectors Directory - Recommended The easiest way to use the Blockscout MCP server with Claude (Web, Desktop, and Code) is through the official [Anthropic Connectors Directory](https://claude.com/connectors). This provides a native, managed installation experience with automatic updates. #### Installation ##### Option 1: Direct Link Visit [claude.com/connectors/blockscout](https://claude.com/connectors/blockscout) and click links in "Used in" section to install the Blockscout connector. ##### Option 2: Via Settings 1. Open Claude (Web or Desktop app) 2. Go to Settings > Connectors > Browse connectors 3. Search for "Blockscout" 4. Click "Connect" to install > **Note:** Connectors require a paid Claude plan (Pro, Team, Max, or Enterprise). > **Limitations:** Due to the use of a shared access key, there may be restrictions on connector access and capabilities. ### Claude Desktop Setup To use the official Blockscout MCP server with your own PRO API key in Claude Desktop, choose one of the following options: #### Option 1: MCP Bundle (MCPB) — Recommended **Best for:** Easy installation and automatic updates. 1. Download the latest `blockscout-mcp.mcpb` from [GitHub releases](https://github.com/blockscout/mcp-server/releases). 2. Double-click the `.mcpb` file to install it in Claude Desktop. 3. Configure your Blockscout PRO API key when prompted. 4. The extension automatically connects to the hosted Blockscout MCP service. #### Option 2: Docker Proxy > **Note:** Docker is required for this setup. **Best for:** Users comfortable with command-line tools and custom configurations. 1. Open Claude Desktop and click on Settings 2. Navigate to the "Developer" section 3. Click "Edit Config" 4. Open the file `claude_desktop_config.json` and configure the server: ```json { "mcpServers": { "blockscout": { "command": "docker", "args": [ "run", "--rm", "-i", "sparfenyuk/mcp-proxy:latest", "--transport", "streamablehttp", "--headers", "Blockscout-MCP-Pro-Api-Key", "proapi_your_key_here", "--headers", "Blockscout-MCP-Intermediary", "ClaudeDesktop", "https://mcp.blockscout.com/mcp" ] } } } ``` 5. Save the file and restart Claude Desktop ### Claude Code Setup Pass your PRO API key via the `Blockscout-MCP-Pro-Api-Key` header when adding the server: ```sh claude mcp add --transport http blockscout https://mcp.blockscout.com/mcp \ --header "Blockscout-MCP-Pro-Api-Key: proapi_your_key_here" ``` After running this command, Blockscout will be available as an MCP server in Claude Code, allowing you to access and analyze blockchain data directly from your coding environment. ### ChatGPT Apps Setup Install the Blockscout app from the [ChatGPT Apps marketplace](https://chatgpt.com/apps?q=Blockscout): 1. Open the [Blockscout app page](https://chatgpt.com/apps/blockscout-blockchain-data/asdk_app_69a880b0d024819182db60f36cb48420) (or search for "Blockscout" in the [ChatGPT Apps directory](https://chatgpt.com/apps?q=Blockscout)). 2. Click "Connect" to enable the app for your ChatGPT account. ### Codex App Setup 1. Open Codex and go to **Settings > MCP Servers > Add server**. 2. Set **Name** to `Blockscout`, select the **Streamable HTTP** tab, and set **URL** to `https://mcp.blockscout.com/mcp`. 3. Under **Headers**, add a header with key `Blockscout-MCP-Pro-Api-Key` and value `proapi_your_key_here`. 4. Save and restart the Codex app. ### Codex CLI Setup Codex CLI cannot attach a custom header from the command line, so configure it in two steps: 1. Scaffold the server entry: ```sh codex mcp add Blockscout --url https://mcp.blockscout.com/mcp ``` 2. Edit `~/.codex/config.toml` to add the PRO API key header and enable the streamable-HTTP MCP client (required for remote MCP servers to connect). The resulting configuration should look like this: ```toml [features] experimental_use_rmcp_client = true [mcp_servers.Blockscout] url = "https://mcp.blockscout.com/mcp" http_headers = { "Blockscout-MCP-Pro-Api-Key" = "proapi_your_key_here" } ``` ### Cursor Setup Add the server to your Cursor MCP configuration — either the project-level `.cursor/mcp.json` or the global `~/.cursor/mcp.json` — supplying your PRO API key via the `Blockscout-MCP-Pro-Api-Key` header: ```json { "mcpServers": { "blockscout": { "url": "https://mcp.blockscout.com/mcp", "timeout": 180000, "headers": { "Blockscout-MCP-Pro-Api-Key": "proapi_your_key_here" } } } } ``` ### Local Development Setup (For Developers) If you want to run the server locally for development purposes: ```json { "mcpServers": { "blockscout": { "command": "docker", "args": [ "run", "--rm", "-i", "ghcr.io/blockscout/mcp-server:latest" ] } } } ``` ## Technical details Refer to [SPEC.md](SPEC.md) for the technical details. ## Repository Structure Refer to [AGENTS.md](AGENTS.md) for the repository structure. ## Testing Refer to [TESTING.md](TESTING.md) for comprehensive instructions on running both **unit and integration tests**. ## Tool Descriptions 1. `__unlock_blockchain_analysis__()` - Initializes a Blockscout MCP session: returns server reference data, the `blockscout-analysis` skill pointer, and the URI resolution rule. Call it once per session, before any other tool. 2. `get_chains_list(query=None)` - Returns a list of supported chains, with optional filtering by name, chain ID, native currency, or ecosystem. 3. `get_address_by_ens_name(name)` - Converts an ENS domain name to its corresponding Ethereum address. 4. `lookup_token_by_symbol(chain_id, symbol)` - Searches for token addresses by symbol or name, returning multiple potential matches. 5. `get_contract_abi(chain_id, address)` - Retrieves the ABI (Application Binary Interface) for a smart contract. 6. `inspect_contract_code(chain_id, address, file_name=None)` - Allows getting the source files of verified contracts. 7. `get_address_info(chain_id, address)` - Gets comprehensive information about an address including balance, ENS association, contract status, token details, and public tags. 8. `get_tokens_by_address(chain_id, address, cursor=None)` - Returns detailed ERC20 token holdings for an address with enriched metadata and market data. 9. `get_block_number(chain_id, [datetime])` - Retrieves the block number and timestamp for a specific date/time or the latest block. 10. `get_transactions_by_address(chain_id, address, age_from, age_to, methods, cursor=None)` - Gets transactions for an address within a specific time range with optional method filtering. 11. `get_token_transfers_by_address(chain_id, address, age_from, age_to, token, cursor=None)` - Returns ERC-20 token transfers for an address within a specific time range. 12. `nft_tokens_by_address(chain_id, address, cursor=None)` - Retrieves NFT tokens owned by an address, grouped by collection. 13. `get_block_info(chain_id, number_or_hash, include_transactions=False)` - Returns block information including timestamp, gas used, burnt fees, and transaction count. Can optionally include a list of transaction hashes. 14. `get_transaction_info(chain_id, hash, include_raw_input=False)` - Gets comprehensive transaction information with decoded input parameters and detailed token transfers. 15. `read_contract(chain_id, address, abi, function_name, args='[]', block='latest')` - Executes a read-only smart contract function and returns its result. The `abi` argument is a JSON object describing the specific function's signature. 16. `direct_api_call(chain_id, endpoint_path, query_params=None, cursor=None, method='GET', json_body=None)` - Calls a raw Blockscout API endpoint for advanced or chain-specific data. Supports GET (default) and POST requests with JSON body. ## Example Prompts for AI Agents ```plaintext Is any approval set for OP token on Optimism chain by `zeaver.eth`? ``` ```plaintext Calculate the total gas fees paid on Ethereum by address `0xcafe...cafe` in May 2025. ``` ```plaintext Which 10 most recent logs were emitted by `0xFe89cc7aBB2C4183683ab71653C4cdc9B02D44b7` before `Nov 08 2024 04:21:35 AM (-06:00 UTC)`? ``` ```plaintext Tell me more about the transaction `0xf8a55721f7e2dcf85690aaf81519f7bc820bc58a878fa5f81b12aef5ccda0efb` on Redstone rollup. ``` ```plaintext Is there any blacklisting functionality of USDT token on Arbitrum One? ``` ```plaintext What is the latest block on Gnosis Chain and who is the block minter? Were any funds moved from this minter recently? ``` ```plaintext When the most recent reward distribution of Kinto token was made to the wallet `0x7D467D99028199D99B1c91850C4dea0c82aDDF52` in Kinto chain? ``` ```plaintext Which methods of `0x1c479675ad559DC151F6Ec7ed3FbF8ceE79582B6` on the Ethereum mainnet could emit `SequencerBatchDelivered`? ``` ```plaintext What is the most recent executed cross-chain message sent from the Arbitrum Sepolia rollup to the base layer? ``` ## Development & Deployment ### Local Installation Clone the repository and install dependencies: ```bash git clone https://github.com/blockscout/mcp-server.git cd mcp-server uv pip install -e . # or `pip install -e .` ``` To customize the leading part of the `User-Agent` header used for RPC requests, set the `BLOCKSCOUT_MCP_USER_AGENT` environment variable (defaults to "Blockscout MCP"). The server version is appended automatically. ### Providing the PRO API Key to the Server When you run the server yourself, provide the [Blockscout PRO API key](#blockscout-pro-api-key) through the `BLOCKSCOUT_PRO_API_KEY` environment variable — exported in your shell or placed in a gitignored `.env` file in the project root. This enables all data access, public-tag enrichment, and contract reads. Never commit the key or embed it in a client-shipped binary; when running via Docker, pass it at runtime (e.g. `-e BLOCKSCOUT_PRO_API_KEY=...`) rather than baking it into the image. ```bash export BLOCKSCOUT_PRO_API_KEY=proapi_your_key_here ``` **Client-supplied keys (HTTP transports).** When the server runs in HTTP mode, a client can supply its own PRO API key in a request header — by default `Blockscout-MCP-Pro-Api-Key`, configurable via `BLOCKSCOUT_PRO_API_KEY_HEADER` (set it to an empty string to disable client-supplied keys entirely). This works the same way for both HTTP transports — MCP-over-HTTP tool calls and the REST API. A client-supplied key takes precedence over `BLOCKSCOUT_PRO_API_KEY` for that request; if the client sends no key, the server falls back to its own configured key; if neither is present, the request fails with the not-configured error. A client key that is present but malformed fails any request that needs the PRO API with no fallback (the server never silently uses its own key in place of a bad client key); tools that don't use the PRO API are unaffected. This makes it possible to run a shared HTTP server where each client authenticates with its own key. **Low-credit warning.** Access to the PRO API is metered in credits. When the remaining balance reported by the API drops below a configurable threshold, every data tool appends an advisory note to its response, prompting operators to top up so PRO API access stays ready for continued high-volume usage. The threshold is set via `BLOCKSCOUT_PRO_API_LOW_CREDITS_THRESHOLD` (default `5000` credits; set to `0` to disable the note). The note fires for any balance below the threshold, including zero and negative balances. **PRO API key requirement notice.** `BLOCKSCOUT_PRO_API_KEY_REQUIRED_NOTICE` holds an operator-configured notice that the server appends as the last entry of the `notes` field of tool responses whose requests did not carry the client's own (well-formed) PRO API key. It exists to announce the official public server's migration to mandatory client-supplied keys, so only the official deployment is expected to set it. When the variable is unset or empty (the default), the feature is completely off. Community and self-hosted operators should leave it empty — in particular in stdio mode, where you configure `BLOCKSCOUT_PRO_API_KEY` yourself and no request header can carry a client key, the notice would only repeat a migration message that does not apply to your deployment. ### Running the Server The server runs in `stdio` mode by default: ```bash python -m blockscout_mcp_server ``` **HTTP Mode (MCP only):** To run the server in HTTP Streamable mode (stateless, SSE responses by default): ```bash python -m blockscout_mcp_server --http ``` You can also specify the host and port for the HTTP server: ```bash python -m blockscout_mcp_server --http --http-host 0.0.0.0 --http-port 8080 ``` **Development Mode (Plain JSON Responses):** For development and testing with simple HTTP clients (curl, Insomnia), you can enable plain JSON responses instead of SSE streams: ```bash export BLOCKSCOUT_DEV_JSON_RESPONSE=true python -m blockscout_mcp_server --http ``` **Note:** This disables Server-Sent Events (SSE) and progress notifications. Only use this for local testing and debugging. **Tunneling with Ngrok (Development Mode):** The Python MCP SDK enforces DNS rebinding protection, which blocks requests from ngrok tunnels by default. To enable tunneling for development and testing: 1. Start an ngrok tunnel to your local server: ```bash ngrok http 8000 ``` 1. Configure the allowed host and origin using your ngrok URL: ```bash export BLOCKSCOUT_MCP_ALLOWED_HOSTS="your-tunnel-id.ngrok-free.app" export BLOCKSCOUT_MCP_ALLOWED_ORIGINS="https://your-tunnel-id.ngrok-free.app" python -m blockscout_mcp_server --http ``` **Note:** These settings are primarily for development use. When these variables are not set, DNS rebinding protection is automatically determined by the server's bind host: enabled for localhost, disabled for non-localhost (e.g., `0.0.0.0`). If your Host header includes a non-standard port, use the `:*` wildcard suffix (e.g., `"example.com:*"`) or specify the exact host:port value. For more details on ngrok tunneling with MCP servers, see the [OpenAI Apps SDK Examples documentation](https://github.com/openai/openai-apps-sdk-examples/blob/main/README.md#testing-in-chatgpt). **HTTP Mode with REST API:** To enable the versioned REST API alongside the MCP endpoint, use the `--rest` flag (which requires `--http`). ```bash python -m blockscout_mcp_server --http --rest ``` With custom host and port: ```bash python -m blockscout_mcp_server --http --rest --http-host 0.0.0.0 --http-port 8080 ``` **CLI Options:** - `--http`: Enables HTTP Streamable mode. - `--http-host TEXT`: Host to bind the HTTP server to (default: `127.0.0.1`). - `--http-port INTEGER`: Port for the HTTP server (default: `8000`). - `--rest`: Enables the REST API (requires `--http`). ### Building Docker Image Locally Initialize the bundled skill submodule, bake its commit metadata into the Docker build context, then build the image: ```bash git submodule update --init --recursive agent-skills python scripts/bake_skill_metadata.py docker build -t ghcr.io/blockscout/mcp-server:latest . ``` ### Pulling from GitHub Container Registry Pull the pre-built image: ```bash docker pull ghcr.io/blockscout/mcp-server:latest ``` ### Running with Docker **HTTP Mode (MCP only):** To run the Docker container in HTTP mode with port mapping: ```bash docker run --rm -p 8000:8000 ghcr.io/blockscout/mcp-server:latest python -m blockscout_mcp_server --http --http-host 0.0.0.0 ``` With custom port: ```bash docker run --rm -p 8080:8080 ghcr.io/blockscout/mcp-server:latest python -m blockscout_mcp_server --http --http-host 0.0.0.0 --http-port 8080 ``` **HTTP Mode with REST API:** To run with the REST API enabled: ```bash docker run --rm -p 8000:8000 ghcr.io/blockscout/mcp-server:latest python -m blockscout_mcp_server --http --rest --http-host 0.0.0.0 ``` **Note:** When running in HTTP mode with Docker, use `--http-host 0.0.0.0` to bind to all interfaces so the server is accessible from outside the container. **With a Blockscout PRO API Key:** Pass the key at runtime with `-e` rather than baking it into the image (see [Providing the PRO API Key to the Server](#providing-the-pro-api-key-to-the-server)): ```bash docker run --rm -p 8000:8000 -e BLOCKSCOUT_PRO_API_KEY=proapi_your_key_here \ ghcr.io/blockscout/mcp-server:latest python -m blockscout_mcp_server --http --http-host 0.0.0.0 ``` **With session metering enabled (optional):** Session metering limits how many tool calls a caller without a client-supplied PRO API key may make per session identifier issued by `__unlock_blockchain_analysis__`. It is off by default. Enabling it means setting a signing secret (at least 32 bytes — generate it, don't invent it), and it requires HTTP mode and a server-side PRO API key (metered calls are served upstream on it), plus a persistent volume for the session database. Generate the secret **once** and store it durably (a secret manager, or persistent environment configuration); every restart and redeploy must pass the same stored value: ```bash # Once, not per start: generate the secret and keep it. BLOCKSCOUT_SESSION_SECRET="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')" docker run --rm -p 8000:8000 \ -v blockscout-mcp-sessions:/data \ -e BLOCKSCOUT_SESSION_SECRET="$BLOCKSCOUT_SESSION_SECRET" \ -e BLOCKSCOUT_SESSION_DB_PATH=/data/sessions.db \ -e BLOCKSCOUT_PRO_API_KEY=proapi_your_key_here \ ghcr.io/blockscout/mcp-server:latest python -m blockscout_mcp_server --http --http-host 0.0.0.0 ``` Most deployments do not need any of this: leave `BLOCKSCOUT_SESSION_SECRET` unset (the default) and no volume is required. Losing the volume or rotating the secret invalidates live session identifiers **by design**; the exposure is bounded by the configured TTL. Re-generating the secret inline on every `docker run` is the accidental form of that rotation — it wipes all live identifiers on each restart even though the database volume survived, so never embed the generation command in the start command. Restoring an older copy of the database revives the budgets it recorded — after a historical restore, rotate the secret unless that is intended. Optional knobs: `BLOCKSCOUT_SESSION_MCP_MAX_CALLS` and `BLOCKSCOUT_SESSION_REST_MAX_CALLS` (per-surface call ceilings over one shared per-identifier counter; both default `5`; `0` closes metered access on that surface while leaving identifier issuance and `get_chains_list` navigation open), `BLOCKSCOUT_SESSION_TTL_SECONDS` (default `900`), and `BLOCKSCOUT_SESSION_SWEEP_INTERVAL_SECONDS` (how often expired session rows are cleaned up; default: once per TTL). **Stdio Mode:** The default stdio mode is designed for use with MCP hosts/clients (like Claude Desktop, Cursor) and doesn't make sense to run directly with Docker without an MCP client managing the communication. ### Testing with Claude Desktop Use MCP bundle to test the server with Claude Desktop. 1. Build the bundle as per instructions in [mcpb/README.md](mcpb/README.md). 2. Open Claude Desktop. 3. Double-click to open the `blockscout-mcp-dev.mcpb` file to automatically install the bundle. 4. Configure the Blockscout MCP Server URL when prompted (default: `http://127.0.0.1:8000/mcp`) ## Privacy and Anonymous Telemetry To help us improve the Blockscout MCP Server, community-run instances of the server collect anonymous usage data by default. This helps us understand which tools are most popular and guides our development efforts. **What we collect:** - The name of the tool being called (e.g., `get_block_number`). - The parameters provided to the tool (the `session_id` parameter is masked to a placeholder before transmission). - The version of the Blockscout MCP Server being used. - A one-way, non-reversible hash (SHA-256) of the PRO API key available to authorize the request, when one is present. This is a derived fingerprint only — the key itself is never transmitted and cannot be recovered from the hash. **What we DO NOT collect:** - We do not collect any personal data, IP addresses (the central server uses the sender's IP for geolocation via Mixpanel and then discards it), or secrets and private keys themselves. The PRO API key in particular is never transmitted — only its one-way, non-reversible fingerprint described above, from which the key cannot be recovered. ### How to Opt-Out You can disable this feature at any time by setting the following environment variable: ```bash export BLOCKSCOUT_DISABLE_COMMUNITY_TELEMETRY=true ``` ## License [![License: Blockscout Software Licence](https://img.shields.io/badge/License-Blockscout%20Software%20Licence-blue.svg)](LICENSE) This project is licensed under the Blockscout Software Licence. See the [LICENSE](LICENSE) file for full terms.