{"id":28431786,"url":"https://github.com/blockscout/mcp-server","last_synced_at":"2026-03-03T23:06:57.239Z","repository":{"id":297198834,"uuid":"995676870","full_name":"blockscout/mcp-server","owner":"blockscout","description":"Wraps Blockscout APIs and exposes blockchain data by Model Context Protocol","archived":false,"fork":false,"pushed_at":"2025-09-02T20:38:42.000Z","size":433,"stargazers_count":19,"open_issues_count":9,"forks_count":9,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-02T20:41:05.842Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blockscout.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-06-03T21:08:52.000Z","updated_at":"2025-09-02T18:53:54.000Z","dependencies_parsed_at":"2025-06-26T00:18:18.086Z","dependency_job_id":"fb344482-34c5-4f20-84ab-e3db396e18bd","html_url":"https://github.com/blockscout/mcp-server","commit_stats":null,"previous_names":["blockscout/mcp-server"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/blockscout/mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockscout%2Fmcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockscout%2Fmcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockscout%2Fmcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockscout%2Fmcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blockscout","download_url":"https://codeload.github.com/blockscout/mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockscout%2Fmcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275124939,"owners_count":25409799,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-14T02:00:10.474Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-05T16:08:32.218Z","updated_at":"2026-01-30T01:53:11.526Z","avatar_url":"https://github.com/blockscout.png","language":"Python","funding_links":[],"categories":["📚 Projects (1974 total)","Uncategorized","Infrastructure and Observability","🤖 AI/ML","AI \u0026 Agentic Development","Blockchain Data Infrastructure"],"sub_categories":["MCP Servers","How to Submit","Tools"],"readme":"# Blockscout MCP Server\n\n[![smithery badge](https://smithery.ai/badge/@blockscout/mcp-server)](https://smithery.ai/server/@blockscout/mcp-server)\n\n\u003ca href=\"https://glama.ai/mcp/servers/@blockscout/mcp-server\"\u003e\n  \u003cimg width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/@blockscout/mcp-server/badge\" alt=\"Blockscout Server MCP server\" /\u003e\n\u003c/a\u003e\n\nThe 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.\n\nThis 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.\n\n**Key Features:**\n\n- Contextual blockchain data access for AI tools\n- Multi-chain support via getting Blockscout instance URLs from Chainscout\n- **Versioned REST API**: Provides a standard, web-friendly interface to all MCP tools. See [API.md](API.md) for full documentation.\n- Custom instructions for MCP host to use the server\n- Intelligent context optimization to conserve LLM tokens while preserving data accessibility\n- Smart response slicing with configurable page sizes to prevent context overflow\n- Opaque cursor pagination using Base64URL-encoded strings instead of complex parameters\n- Automatic truncation of large data fields with clear indicators and access guidance\n- Standardized ToolResponse model with structured JSON responses and follow-up instructions\n- Enhanced observability with MCP progress notifications and periodic updates for long-running operations\n\n## Configuring MCP Clients\n\n### Using Claude Connectors Directory - Recommended\n\nThe easiest way to use the Blockscout MCP server with Claude ( Claude Web, Claude Desktop and Claude Code) is through the official [Anthropic Connectors Directory](https://claude.com/connectors). This provides a native, managed installation experience with automatic updates.\n\n#### Installation\n\n##### Option 1: Direct Link\n\nVisit [claude.com/connectors/blockscout](https://claude.com/connectors/blockscout) and click links in \"Used in\" section to install the Blockscout connector.\n\n##### Option 2: Via Settings\n\n1. Open Claude (Web or Desktop app)\n2. Go to Settings \u003e Connectors \u003e Browse connectors\n3. Search for \"Blockscout\"\n4. Click \"Connect\" to install\n\n\u003e **Note:** Connectors require a paid Claude plan (Pro, Team, Max, or Enterprise).\n\n### Claude Code Setup\n\nTo quickly install the Blockscout MCP server for use with Claude Code, run the following command in your terminal:\n\n```sh\nclaude mcp add --transport http blockscout https://mcp.blockscout.com/mcp\n```\n\nAfter 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.\n\n### Cursor Setup\n\nUse [this deeplink](https://cursor.com/en/install-mcp?name=blockscout\u0026config=eyJ1cmwiOiJodHRwczovL21jcC5ibG9ja3Njb3V0LmNvbS9tY3AiLCJ0aW1lb3V0IjoxODAwMDB9) to install the Blockscout MCP server in Cursor.\n\n### Gemini CLI Setup\n\n1. Add the following configuration to your `~/.gemini/settings.json` file:\n\n    ```json\n    {\n      \"mcpServers\": {\n        \"blockscout\": {\n          \"httpUrl\": \"https://mcp.blockscout.com/mcp\",\n          \"timeout\": 180000\n        }\n      }\n    }\n    ```\n\n2. For detailed Gemini CLI MCP server configuration instructions, see the [official documentation](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md).\n\n## Try Blockscout X-Ray GPT\n\nExperience the power of the Blockscout MCP server through our showcase GPT: **[Blockscout X-Ray](https://chatgpt.com/g/g-68a7f315edf481918641bd0ed1e60f8b-blockscout-x-ray)**\n\nThis GPT demonstrates the full capabilities of the MCP server, providing intelligent blockchain analysis and insights. It's a great way to explore what's possible when AI agents have contextual access to blockchain data.\n\n### Local Development Setup (For Developers)\n\nIf you want to run the server locally for development purposes:\n\n```json\n{\n  \"mcpServers\": {\n    \"blockscout\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"--rm\", \"-i\",\n        \"ghcr.io/blockscout/mcp-server:latest\"\n      ]\n    }\n  }\n}\n```\n\n## Technical details\n\nRefer to [SPEC.md](SPEC.md) for the technical details.\n\n## Repository Structure\n\nRefer to [AGENTS.md](AGENTS.md) for the repository structure.\n\n## Testing\n\nRefer to [TESTING.md](TESTING.md) for comprehensive instructions on running both **unit and integration tests**.\n\n## Tool Descriptions\n\n1. `__unlock_blockchain_analysis__()` - Provides custom instructions for the MCP host to use the server. This is a mandatory first step before using other tools.\n2. `get_chains_list()` - Returns a list of all known chains.\n3. `get_address_by_ens_name(name)` - Converts an ENS domain name to its corresponding Ethereum address.\n4. `lookup_token_by_symbol(chain_id, symbol)` - Searches for token addresses by symbol or name, returning multiple potential matches.\n5. `get_contract_abi(chain_id, address)` - Retrieves the ABI (Application Binary Interface) for a smart contract.\n6. `inspect_contract_code(chain_id, address, file_name=None)` - Allows getting the source files of verified contracts.\n7. `get_address_info(chain_id, address)` - Gets comprehensive information about an address including balance, ENS association, contract status, token details, and public tags.\n8. `get_tokens_by_address(chain_id, address, cursor=None)` - Returns detailed ERC20 token holdings for an address with enriched metadata and market data.\n9. `get_block_number(chain_id, [datetime])` - Retrieves the block number and timestamp for a specific date/time or the latest block.\n10. `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.\n11. `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.\n12. `nft_tokens_by_address(chain_id, address, cursor=None)` - Retrieves NFT tokens owned by an address, grouped by collection.\n13. `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.\n14. `get_transaction_info(chain_id, hash, include_raw_input=False)` - Gets comprehensive transaction information with decoded input parameters and detailed token transfers.\n15. `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.\n16. `direct_api_call(chain_id, endpoint_path, query_params=None, cursor=None)` - Calls a curated raw Blockscout API endpoint for specialized or chain-specific data.\n\n## Example Prompts for AI Agents\n\n```plaintext\nIs any approval set for OP token on Optimism chain by `zeaver.eth`?\n```\n\n```plaintext\nCalculate the total gas fees paid on Ethereum by address `0xcafe...cafe` in May 2025.\n```\n\n```plaintext\nWhich 10 most recent logs were emitted by `0xFe89cc7aBB2C4183683ab71653C4cdc9B02D44b7`\nbefore `Nov 08 2024 04:21:35 AM (-06:00 UTC)`?\n```\n\n```plaintext\nTell me more about the transaction `0xf8a55721f7e2dcf85690aaf81519f7bc820bc58a878fa5f81b12aef5ccda0efb`\non Redstone rollup.\n```\n\n```plaintext\nIs there any blacklisting functionality of USDT token on Arbitrum One?\n```\n\n```plaintext\nWhat is the latest block on Gnosis Chain and who is the block minter?\nWere any funds moved from this minter recently?\n```\n\n```plaintext\nWhen the most recent reward distribution of Kinto token was made to the wallet\n`0x7D467D99028199D99B1c91850C4dea0c82aDDF52` in Kinto chain?\n```\n\n```plaintext\nWhich methods of `0x1c479675ad559DC151F6Ec7ed3FbF8ceE79582B6` on the Ethereum \nmainnet could emit `SequencerBatchDelivered`?\n```\n\n```plaintext\nWhat is the most recent executed cross-chain message sent from the Arbitrum Sepolia\nrollup to the base layer?\n```\n\n## Development \u0026 Deployment\n\n### Local Installation\n\nClone the repository and install dependencies:\n\n```bash\ngit clone https://github.com/blockscout/mcp-server.git\ncd mcp-server\nuv pip install -e . # or `pip install -e .`\n```\n\nTo customize the leading part of the `User-Agent` header used for RPC requests,\nset the `BLOCKSCOUT_MCP_USER_AGENT` environment variable (defaults to\n\"Blockscout MCP\"). The server version is appended automatically.\n\n### Running the Server\n\nThe server runs in `stdio` mode by default:\n\n```bash\npython -m blockscout_mcp_server\n```\n\n**HTTP Mode (MCP only):**\n\nTo run the server in HTTP Streamable mode (stateless, JSON responses):\n\n```bash\npython -m blockscout_mcp_server --http\n```\n\nYou can also specify the host and port for the HTTP server:\n\n```bash\npython -m blockscout_mcp_server --http --http-host 0.0.0.0 --http-port 8080\n```\n\n**HTTP Mode with REST API:**\n\nTo enable the versioned REST API alongside the MCP endpoint, use the `--rest` flag (which requires `--http`).\n\n```bash\npython -m blockscout_mcp_server --http --rest\n```\n\nWith custom host and port:\n\n```bash\npython -m blockscout_mcp_server --http --rest --http-host 0.0.0.0 --http-port 8080\n```\n\n**CLI Options:**\n\n- `--http`: Enables HTTP Streamable mode.\n- `--http-host TEXT`: Host to bind the HTTP server to (default: `127.0.0.1`).\n- `--http-port INTEGER`: Port for the HTTP server (default: `8000`).\n- `--rest`: Enables the REST API (requires `--http`).\n\n### Building Docker Image Locally\n\nBuild the Docker image with the official tag:\n\n```bash\ndocker build -t ghcr.io/blockscout/mcp-server:latest .\n```\n\n### Pulling from GitHub Container Registry\n\nPull the pre-built image:\n\n```bash\ndocker pull ghcr.io/blockscout/mcp-server:latest\n```\n\n### Running with Docker\n\n**HTTP Mode (MCP only):**\n\nTo run the Docker container in HTTP mode with port mapping:\n\n```bash\ndocker run --rm -p 8000:8000 ghcr.io/blockscout/mcp-server:latest python -m blockscout_mcp_server --http --http-host 0.0.0.0\n```\n\nWith custom port:\n\n```bash\ndocker 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\n```\n\n**HTTP Mode with REST API:**\n\nTo run with the REST API enabled:\n\n```bash\ndocker run --rm -p 8000:8000 ghcr.io/blockscout/mcp-server:latest python -m blockscout_mcp_server --http --rest --http-host 0.0.0.0\n```\n\n**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.\n\n**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.\n\n### Testing with Claude Desktop\n\nUse MCP bundle to test the server with Claude Desktop.\n\n1. Build the bundle as per instructions in [mcpb/README.md](mcpb/README.md).\n2. Open Claude Desktop.\n3. Double-click to open the `blockscout-mcp-dev.mcpb` file to automatically install the bundle.\n4. Configure the Blockscout MCP Server URL when prompted (default: `http://127.0.0.1:8000/mcp`)\n\n## Privacy and Anonymous Telemetry\n\nTo 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.\n\n**What we collect:**\n\n- The name of the tool being called (e.g., `get_block_number`).\n- The parameters provided to the tool.\n- The version of the Blockscout MCP Server being used.\n\n**What we DO NOT collect:**\n\n- 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), secrets, or private keys.\n\n### How to Opt-Out\n\nYou can disable this feature at any time by setting the following environment variable:\n\n```bash\nexport BLOCKSCOUT_DISABLE_COMMUNITY_TELEMETRY=true\n```\n\n## License\n\nThis project is primarily distributed under the terms of the MIT license. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblockscout%2Fmcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblockscout%2Fmcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblockscout%2Fmcp-server/lists"}