Heurist Mesh MCP Server

1# Heurist Mesh MCP Server
2 
3![mesh-2](https://github.com/user-attachments/assets/da67c0e6-0709-4f28-ab82-8abfc0c0734c)
4 
5A Model Context Protocol (MCP) server that connects to [Heurist Mesh](https://github.com/heurist-network/heurist-agent-framework/tree/main/mesh) APIs - your gateway to Web3 intelligence.
6 
7**[Heurist Mesh](https://mesh.heurist.ai)** is the skills marketplace for AI agents. General-purpose AI models lack specialized knowledge about Web3 and often fail to deliver accurate results. Heurist Mesh provides 30+ specialized AI agents that are experts in crypto analytics, ready to give your AI applications the Web3 expertise they need.
8 
9<a href="https://glama.ai/mcp/servers/@heurist-network/heurist-mesh-mcp-server">
10  <img width="380" height="200" src="https://glama.ai/mcp/servers/@heurist-network/heurist-mesh-mcp-server/badge" alt="Mesh Agent Server MCP server" />
11</a>
12 
13## Features
14- **Gateway to Web3 Intelligence**: Access 30+ specialized crypto analytics agents via MCP
15- **Optimized for AI**: Input/output formats optimized for AI agents - fewer tool calls, less token usage
16- Supports both SSE and stdio transports
17- Works with Claude, Cursor, Claude Desktop, and other MCP-compatible interfaces
18- Use one API key to access multiple services (CoinGecko, DexScreener, Twitter analytics, and more)
19 
20## 🔥 Just In: Customize Your Agents and Create Managed MCP Servers On-Demand
21You can use [Heurist Mesh Console](https://mesh.heurist.ai/console) to create SSE MCP Servers. Select your agents and compose a personalized swarm for your tasks!
22 
23## Hosted SSE Endpoint
24We provide a hosted SSE endpoint at https://mesh.heurist.xyz/mcp/sse. **Authentication is required** - you need a [Heurist API key](https://dev-api-form.heurist.ai/) (use invite code "claude" for free credits).
25 
26Provide your API key via:
27- `X-HEURIST-API-KEY` header (recommended)
28- `Authorization: Bearer <your-api-key>` header
29- `api_key` query parameter
30 
31This endpoint includes tools from recommended agents for comprehensive Web3 intelligence:
32 
33| Agent | Description |
34|-------|-------------|
35| `TokenResolverAgent` | Find tokens by address/symbol/name, return normalized profiles and top DEX pools |
36| `TrendingTokenAgent` | Aggregates trending tokens from GMGN, CoinGecko, Pump.fun, Dexscreener, Zora and Twitter |
37| `TwitterIntelligenceAgent` | Twitter/X timeline, tweet detail, and smart search |
38| `ExaSearchDigestAgent` | Web search with concise LLM summarization |
39| `FundingRateAgent` | Binance funding rates, open interest, and spot-futures opportunities |
40| `AIXBTProjectInfoAgent` | Trending project info, fundamental analysis, and market summary |
41| `ZerionWalletAnalysisAgent` | EVM wallet token and NFT holdings analysis |
42 
43This is a shared server and the performance may be unstable. For production use, we recommend self-hosting or using [Heurist Mesh Console](https://mesh.heurist.ai/console) to create dedicated servers.
44 
45Cursor can directly access SSE servers. For Claude Desktop users, we recommend installing [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy) to connect to the SSE server.
46 
47## Prerequisites
48 
49- Python 3.10 or higher
50- UV package manager (recommended)
51- OR Docker
52- [Get a Heurist API key](https://docs.heurist.ai/protocol-overview/credits) or you can [claim free API credits](https://dev-api-form.heurist.ai/) with invite code "claude"
53 
54## Installation
55### Using UV (Recommended)
56```bash
57# Clone the repository
58git clone https://github.com/heurist-network/heurist-mesh-mcp-server.git
59cd heurist-mesh-mcp-server
60 
61# Install the package
62uv pip install -e .
63```
64 
65### Using Docker
66```bash
67# Clone the repository
68git clone https://github.com/heurist-network/heurist-mesh-mcp-server.git
69cd heurist-mesh-mcp-server
70 
71# Build the Docker image
72docker build -t mesh-tool-server .
73```
74## Usage
75### Option 1: Run with stdio Transport (for Claude Desktop)
76#### Using UV
77To use this with Claude Desktop, add the following to your `claude_desktop_config.json`:
78```bash
79{
80  "mcpServers": {
81    "heurist-mesh-agent": {
82      "command": "uv",
83      "args": [
84        "--directory",
85        "/path/to/heurist-mesh-mcp-server/mesh_mcp_server",  // Update this path
86        "run",
87        "mesh-tool-server"
88      ],
89      "env": {
90        "HEURIST_API_KEY": "your-api-key-here"  // Update this key
91      }
92    }
93  }
94}
95```
96#### Using Docker
97Alternatively, you can use Docker with Claude Desktop by adding this to your `claude_desktop_config.json`:
98```bash
99{
100  "mcpServers": {
101    "mesh-agent": {
102      "command": "docker",
103      "args": [
104        "run",
105        "--rm",
106        "-i",
107        "-e", "TRANSPORT=stdio",
108        "-e", "HEURIST_API_KEY=your-api-key-here",  // Update this key
109        "mesh-tool-server"
110      ]
111    }
112  }
113}
114```
115 
116Replace `/path/to/heurist-mesh-mcp-server` with the actual path to the repository and `your-api-key-here` with your Heurist API key.
117 
118### Option 2: Run with SSE Transport (for Cursor)
119#### Setting up Environment Variables in `.env`
120```bash
121cp .env.example .env
122HEURIST_API_KEY=your-api-key-here
123```
124#### Using UV:
125```bash
126uv run mesh-tool-server --transport sse --port 8000
127```
128#### Using Docker:
129```bash
130docker run -p 8000:8000 -e PORT=8000 mesh-tool-server
131```
132Then, in Cursor, add the MCP Server URL: **http://0.0.0.0:8000/sse**
133 
134## Available Tools
135Visit https://mesh.heurist.ai/metadata.json or https://mesh.heurist.ai/console to view all 30+ available agents and their tools.
136 
137## Recommended Tools
138These tools from our recommended agents cover most Web3 intelligence use cases:
139 
140| Tool Name | Description | Agent |
141|-----------|-------------|-------|
142| token_search | Find tokens by address, symbol, name, or CoinGecko ID | TokenResolverAgent |
143| token_profile | Get comprehensive token profile with market data, socials, and top pools | TokenResolverAgent |
144| get_trending_tokens | Aggregated trending tokens from multiple sources | TrendingTokenAgent |
145| get_market_summary | AI-generated market summary across all trending sources | TrendingTokenAgent |
146| twitter_search | Smart Twitter search for crypto topics | TwitterIntelligenceAgent |
147| user_timeline | Get recent tweets from a Twitter user | TwitterIntelligenceAgent |
148| tweet_detail | Get detailed info about a specific tweet | TwitterIntelligenceAgent |
149| exa_web_search | Web search with AI summarization | ExaSearchDigestAgent |
150| exa_scrape_url | Scrape and summarize webpage content | ExaSearchDigestAgent |
151| get_all_funding_rates | Get funding rates for all Binance perpetual contracts | FundingRateAgent |
152| get_symbol_oi_and_funding | Get open interest and funding for a specific symbol | FundingRateAgent |
153| find_spot_futures_opportunities | Find arbitrage opportunities between spot and futures | FundingRateAgent |
154| search_projects | Search trending projects with fundamental analysis | AIXBTProjectInfoAgent |
155| get_market_summary | Get AI market summary from AIXBT | AIXBTProjectInfoAgent |
156| fetch_wallet_tokens | Get EVM wallet token holdings | ZerionWalletAnalysisAgent |
157| fetch_wallet_nfts | Get EVM wallet NFT holdings | ZerionWalletAnalysisAgent |
158 
159## Customizing Supported Agents
160The server comes with a default set of recommended agents. To modify which agents are available:
1611. Open the `server.py` file and locate the `Config` class.
1622. Edit the `DEFAULT_AGENTS` list to add or remove agents listed [at Heurist Metadata](https://mesh.heurist.ai/metadata.json)
163```python
164DEFAULT_AGENTS = [
165    "TokenResolverAgent",        # Comprehensive token lookup
166    "TrendingTokenAgent",        # Aggregated trending tokens
167    "TwitterIntelligenceAgent",  # Twitter/X analytics
168    "ExaSearchDigestAgent",      # Web search with summarization
169    "FundingRateAgent",          # Binance funding & OI data
170    "AIXBTProjectInfoAgent",     # Project analysis
171    "ZerionWalletAnalysisAgent", # Wallet holdings
172    # Add more agents as needed
173]
174```
175 
176## License
177This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License.