heurist-mesh

Heurist Mesh MCP Server exposes a gateway to Web3 intelligence by aggregating 30+ specialized crypto analytics agents and exposing them over MCP with both SSE and stdio transports. This server is designed to work with AI-facing clients and tooling (like Claude Desktop, Cursor, or other MCP-compatible interfaces) to provide token research, market summaries, wallet analysis, and on-chain intelligence. Core capabilities include token lookups, trending token data, crypto social signals, web search summarization, funding rate insights, and project fundamentals, all delivered through streamlined MCP tool calls to minimize prompts and token usage.

To use it, run the server locally or via a container, then connect your MCP client to the provided endpoint (for SSE: http://0.0.0.0:8000/sse or your configured port). You can configure Claude Desktop or Cursor to point at this MCP server. In Claude Desktop, you’ll typically set the transport to stdio with uv-based execution or use a Docker-based setup; in Cursor, you’ll point to the SSE endpoint. The server ships with a curated set of tools (e.g., token_search, token_profile, get_trending_tokens, twitter_search, exa_web_search, get_all_funding_rates, fetch_wallet_tokens) corresponding to the Agent offerings listed by Heurist Mesh. If you need broader coverage, you can customize the available agents by editing the server’s default agent list in the Python source.

Prerequisites

• Python 3.10 or higher
• UV package manager (recommended) OR Docker
• Access to a Heurist API key (or free credits via invite code "claude")

Installation (Using UV - Recommended)

1. Clone the repository

git clone https://github.com/heurist-network/heurist-mesh-mcp-server.git
cd heurist-mesh-mcp-server

2. Install in editable mode

uv pip install -e .

3. Set up your environment (optional but recommended to avoid hard-coding keys)

cp .env.example .env
# then add your API key in the .env file or export it in your shell
export HEURIST_API_KEY=your-api-key-here

Installation (Using Docker)

1. Build the Docker image

git clone https://github.com/heurist-network/heurist-mesh-mcp-server.git
cd heurist-mesh-mcp-server
# Build the image (tag as desired)
docker build -t mesh-tool-server .

2. Run the container (example)

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

Notes

• If you plan to use the stdio transport with Claude Desktop, you may need to configure the claude_desktop_config.json accordingly (see README examples).
• For SSE access, ensure your environment exposes the port you choose (default 8000) and use the SSE endpoint exposed by the server.

Tips and common issues:

• Ensure you provide a valid HEURIST_API_KEY. The hosted SSE endpoint requires authentication; without a key, access will be denied.
• When using Docker, ensure you expose the correct port and pass any required environment variables (e.g., TRANSPORT=stdio for stdio usage).
• If you customize DEFAULT_AGENTS in server.py, remember to restart the MCP server for changes to take effect.
• Some users may experience performance variability on a shared SSE endpoint; for production, consider self-hosting or using Heurist Mesh Console to spawn dedicated servers.
• The server supports both standard MCP tooling and specialized Heurist agents; refer to metadata.json and the provided Agent list for available tools.