Heurist Mesh Agent

What is heurist-mesh-mcp-server?

The heurist-mesh-mcp-server is a Model Context Protocol (MCP) server designed to connect to the Heurist Mesh API. It provides AI models, specifically Claude, with access to a wide range of blockchain and web3 tools. Heurist Mesh is an open network of specialized AI agents and tools focusing on web3 domains like blockchain data analysis, smart contract security, token metrics, and blockchain interaction.

How to use heurist-mesh-mcp-server?

Prerequisites:

• Python 3.10 or higher
• UV package manager (recommended) or Docker
• A Heurist API key (can be claimed with invite code "claude")

Installation:

Using UV (Recommended):

git clone https://github.com/heurist-network/heurist-mesh-mcp-server.git
cd heurist-mesh-mcp-server
uv pip install -e .

Using Docker:

git clone https://github.com/heurist-network/heurist-mesh-mcp-server.git
cd heurist-mesh-mcp-server
docker build -t mesh-tool-server .

Usage:

Option 1: Run with stdio Transport (for Claude Desktop)

• Using UV: Add the following to your claude_desktop_config.json (update path and API key):

  {
    "mcpServers": {
      "heurist-mesh-agent": {
        "command": "uv",
        "args": [
          "--directory",
          "/path/to/heurist-mesh-mcp-server/mesh_mcp_server",
          "run",
          "mesh-tool-server"
        ],
        "env": {
          "HEURIST_API_KEY": "your-api-key-here"
        }
      }
    }
  }
  

• Using Docker: Add the following to your claude_desktop_config.json (update API key):

  {
    "mcpServers": {
      "mesh-agent": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "-i",
          "-e", "TRANSPORT=stdio",
          "-e", "HEURIST_API_KEY=your-api-key-here",
          "mesh-tool-server"
        ]
      }
    }
  }
  

Option 2: Run with SSE Transport (for Cursor)

• Set up Environment Variables: Create a .env file:

  cp .env.example .env
  HEURIST_API_KEY=your-api-key-here
  

• Using UV:

uv run mesh-tool-server --transport sse --port 8000 ```

• Using Docker:

docker run -p 8000:8000 -e PORT=8000 mesh-tool-server ```

Then, in Cursor, add the MCP Server URL: `http://0.0.0.0:8000/sse`.

Customizing Supported Agents:

Edit the DEFAULT_AGENTS list in the server.py file to add or remove agents from the Heurist Metadata.

Key Features of heurist-mesh-mcp-server

• Connects to the Heurist Mesh API.
• Loads tools for cryptocurrency data and Web3 use cases.
• Supports both SSE (Server-Sent Events) and stdio (standard input/output) transports.
• Compatible with Claude in Cursor, Claude Desktop, and other MCP-compatible interfaces.
• Enables access to multiple services (e.g., CoinGecko crypto market data, GoPlus token security review) with a single API key.
• Offers a hosted SSE endpoint for common agents like CoingeckoTokenInfoAgent, ElfaTwitterIntelligenceAgent, ExaSearchAgent, DexScreenerTokenInfoAgent, and ZerionWalletAnalysisAgent.
• Allows customization of agents to create personalized swarms via the Heurist Mesh MCP Portal.

Use Cases of heurist-mesh-mcp-server

• Blockchain Analysis: Access specialized AI agents for in-depth analysis of blockchain data.
• Smart Contract Security: Utilize tools for assessing the security of smart contracts.
• Token Metrics: Retrieve and analyze token-related data and market information.
• Blockchain Interaction: Facilitate interactions with various blockchain networks.
• Cryptocurrency Data Retrieval: Get detailed token information, trending cryptocurrencies, and trading pair data from sources like CoinGecko and DexScreener.
• Social Media Intelligence: Analyze Twitter accounts, search for mentions of tokens or topics, and identify trending tokens.
• Web Search and Answering: Perform web searches and get direct answers to questions using tools like ExaSearchAgent and FirecrawlSearchAgent.
• Token Security Audits: Fetch security details of blockchain token contracts using GoplusAnalysisAgent.
• Custom AI Agent Development: Create and manage custom MCP servers with selected agents for specific tasks.

FAQ about heurist-mesh-mcp-server

Q: What is Heurist Mesh? A: Heurist Mesh is an open network of purpose-built AI agents and tools, each specialized in particular web3 domains such as blockchain data analysis, smart contract security, token metrics, and blockchain interaction.

Q: How can I get a Heurist API key? A: You can get a Heurist API key from https://docs.heurist.ai/protocol-overview/credits or claim free API credits with the invite code "claude" at https://dev-api-form.heurist.ai/.

Q: Where can I find a list of available tools? A: You can view all available tools at https://mesh.heurist.ai/metadata.json or https://mcp.heurist.ai/.

Q: Can I customize the agents available in the server? A: Yes, you can customize the agents by editing the DEFAULT_AGENTS list in the server.py file.

Q: What is the difference between stdio and SSE transport? A: Stdio transport is typically used for local applications like Claude Desktop, while SSE (Server-Sent Events) transport is used for web-based applications like Cursor, allowing for real-time communication.

Mesh Agent MCP Server

A Model Context Protocol (MCP) server that connects to Heurist Mesh APIs, providing Claude with access to various blockchain and web3 tools.

Heurist Mesh is an open network of purpose-built AI agents and tools, each specialized in particular web3 domains such as blockchain data analysis, smart contract security, token metrics, and blockchain interaction. We are actively growing the Heurist Mesh ecosystem, continuously integrating more tools to expand its capabilities.

Features

• Connects to the Heurist Mesh API
• Loads tools for cryptocurrency data and Web3 use cases
• Supports both SSE and stdio transports
• Works with Claude in Cursor, Claude Desktop, and other MCP-compatible interfaces
• Use one API key to access multiple services (e.g. CoinGecko crypto market data, GoPlus token security review)

🔥 Just In: Customize Your Agents and Create Managed MCP Servers On-Demand

You can use Heurist Mesh MCP Portal to create SSE MCP Servers. Select your agents and compose a personalized swarm for your tasks!

Hosted SSE Endpoint

We provide a hosted SSE endpoint at https://sequencer-v2.heurist.xyz/mcp/sse. This includes all the tools from the following commonly used agents: CoingeckoTokenInfoAgent, ElfaTwitterIntelligenceAgent, ExaSearchAgent, DexScreenerTokenInfoAgent, ZerionWalletAnalysisAgent. This is a shared server and the performance may be unstable.

Cursor can directly access SSE servers. For Claude Desktop users, we recommend installing mcp-proxy to connect to the SSE server.

Prerequisites

• Python 3.10 or higher
• UV package manager (recommended)
• OR Docker
• Get a Heurist API key or you can claim free API credits with invite code "claude"

Installation

Using UV (Recommended)

# Clone the repository
git clone https://github.com/heurist-network/heurist-mesh-mcp-server.git
cd heurist-mesh-mcp-server

# Install the package
uv pip install -e .

Using Docker

# Clone the repository
git clone https://github.com/heurist-network/heurist-mesh-mcp-server.git
cd heurist-mesh-mcp-server

# Build the Docker image
docker build -t mesh-tool-server .

Usage

Option 1: Run with stdio Transport (for Claude Desktop)

Using UV

To use this with Claude Desktop, add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "heurist-mesh-agent": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/heurist-mesh-mcp-server/mesh_mcp_server",  // Update this path
        "run",
        "mesh-tool-server"
      ],
      "env": {
        "HEURIST_API_KEY": "your-api-key-here"  // Update this key
      }
    }
  }
}

Using Docker

Alternatively, you can use Docker with Claude Desktop by adding this to your claude_desktop_config.json:

{
  "mcpServers": {
    "mesh-agent": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "TRANSPORT=stdio",
        "-e", "HEURIST_API_KEY=your-api-key-here",  // Update this key
        "mesh-tool-server"
      ]
    }
  }
}

Replace /path/to/heurist-mesh-mcp-server with the actual path to the repository and your-api-key-here with your Heurist API key.

Option 2: Run with SSE Transport (for Cursor)

Setting up Environment Variables in .env

cp .env.example .env
HEURIST_API_KEY=your-api-key-here

Using UV:

uv run mesh-tool-server --transport sse --port 8000

Using Docker:

docker run -p 8000:8000 -e PORT=8000 mesh-tool-server

Then, in Cursor, add the MCP Server URL: http://0.0.0.0:8000/sse

Available Tools

Visit https://mesh.heurist.ai/metadata.json or https://mcp.heurist.ai/ to view all available tools.

Featured tools

Tool Name	Description	Agent	Parameters	Required Params
get_coingecko_id	Search for a token by name to get its CoinGecko ID	CoinGeckoTokenInfoAgent	token_name (string): The token name to search for	token_name
get_token_info	Get detailed token information and market data using CoinGecko ID (you can't use the token address or name or symbol)	CoinGeckoTokenInfoAgent	coingecko_id (string): The CoinGecko ID of the token	coingecko_id
get_trending_coins	Get the current top trending cryptocurrencies on CoinGecko	CoinGeckoTokenInfoAgent	-	None
get_specific_pair_info	Get trading pair info by chain and pair address on DexScreener	DexScreenerTokenInfoAgent	chain (string): Chain identifier (e.g., solana, bsc, ethereum, base)pair_address (string): The pair contract address to look up	chain, pair_address
get_token_pairs	Get the trading pairs by chain and token address on DexScreener	DexScreenerTokenInfoAgent	chain (string): Chain identifier (e.g., solana, bsc, ethereum, base)token_address (string): The token contract address to look up all pairs for	chain, token_address
get_token_profiles	Get the basic info of the latest tokens from DexScreener	DexScreenerTokenInfoAgent	-	None
search_pairs	Search for trading pairs on DexScreener by token name, symbol, or address	DexScreenerTokenInfoAgent	search_term (string): Search term (token name, symbol, or address)	search_term
get_trending_tokens	Get current trending tokens on Twitter	ElfaTwitterIntelligenceAgent	time_window (string): Time window to analyze	None
search_account	Analyze a Twitter account with both mention search and account stats	ElfaTwitterIntelligenceAgent	username (string): Twitter username to analyze (without @)days_ago (integer): Number of days to look back for mentionslimit (integer): Maximum number of mention results	username
search_mentions	Search for mentions of specific tokens or topics on Twitter	ElfaTwitterIntelligenceAgent	keywords (array): List of keywords to search fordays_ago (integer): Number of days to look backlimit (integer): Maximum number of results (minimum: 20)	keywords
answer	Get a direct answer to a question using Exa's answer API	ExaSearchAgent	question (string): The question to answer	question
search	Search for webpages related to a query	ExaSearchAgent	search_term (string): The search termlimit (integer): Maximum number of results to return (default: 10)	search_term
search_and_answer	Perform both search and answer operations for a query	ExaSearchAgent	topic (string): The topic to search for and answer	topic
execute_search	Execute a web search query by reading the web pages	FirecrawlSearchAgent	search_term (string): The search term to execute	search_term
generate_queries	Generate related search queries for a topic that can expand the research	FirecrawlSearchAgent	topic (string): The main topic to researchnum_queries (integer): Number of queries to generate	topic
fetch_security_details	Fetch security details of a blockchain token contract	GoplusAnalysisAgent	contract_address (string): The token contract addresschain_id (['integer', 'string']): The blockchain chain ID or 'solana' for Solana tokens. Supported chains: Ethereum (1), Optimism (10), Cronos (25), BSC (56), Gnosis (100), HECO (128), Polygon (137), Fantom (250), KCC (321), zkSync Era (324), ETHW (10001), FON (201022), Arbitrum (42161), Avalanche (43114), Linea Mainnet (59144), Base (8453), Tron (tron), Scroll (534352), opBNB (204), Mantle (5000), ZKFair (42766), Blast (81457), Manta Pacific (169), Berachain Artio Testnet (80085), Merlin (4200), Bitlayer Mainnet (200901), zkLink Nova (810180), X Layer Mainnet (196), Solana (solana)	contract_address

Customizing Supported Agents

The server comes with a default set of agents. To modify which agents are available:

1. Open the server.py file and locate the Config class.
2. Edit the DEFAULT_AGENTS list to add or remove agents listed at Heurist Metadata

DEFAULT_AGENTS = [
    "CoinGeckoTokenInfoAgent",
    "DexScreenerTokenInfoAgent",
    "ElfaTwitterIntelligenceAgent",
    "ExaSearchAgent",
    "FirecrawlSearchAgent",
    "GoplusAnalysisAgent",
    # Add agents here
    "NewAgent"
]

License

This 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.