home / mcp / bigbugai mcp server

BigBugAI MCP Server

Provides a production-ready MCP server exposing BigBugAI tools with stdio and HTTP/SSE transports.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "bigbugai-bigbugai-mcp": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "BTUNIFIED_API": "https://api.bigbug.ai",
        "MCP_RATE_LIMIT": "60/hour",
        "BIGBUGAI_API_KEY": "optional-key",
        "BIGBUGAI_API_TOKEN": "optional-token",
        "BIGBUGAI_MCP_API_KEY": "your-secret"
      }
    }
  }
}

You run a production-ready MCP server that exposes BigBugAI tools over both stdio for local MCP clients and an optional HTTP/SSE transport for remote access. It uses API keys for authentication, supports per-key rate limiting, and returns structured, JSON-stable outputs for reliable tooling integration.

How to use

You can connect with local MCP clients (for example Claude Desktop or Cursor) using the stdio transport, or enable remote access through HTTP/SSE. The stdio mode reads its API key from the environment and applies rate limiting per key. The HTTP mode mounts MCP endpoints under the /mcp path and can be queried via the server URL you run locally.

With stdio, you start the server in a terminal and then couple your MCP client to the process I/O. The server reads BIGBUGAI_MCP_API_KEY from the environment and uses it to enforce rate limits as configured.

With HTTP, you start the HTTP server and then your MCP client can send requests to the /mcp endpoints. The health endpoint at /healthz returns ok when the server is running, and the /mcp path hosts the MCP API and, if available, an SSE stream under /mcp/sse.

How to install

Prerequisites you need before install:

Python 3.11 or later
A working Python environment (virtualenv recommended)
Access to a terminal or shell

Install the MCP package in editable mode with development dependencies:

uv venv
source .venv/bin/activate
uv pip install -e .[dev]

Run in stdio mode (local MCP clients)

Set your API key and endpoint defaults in the environment, then start the stdio MCP server.

export BIGBUGAI_MCP_API_KEY="your-secret"
export BTUNIFIED_API="https://api.bigbug.ai"
uv run -m bigbugai_mcp.server_stdio

Run in HTTP mode (remote MCP access)

Start the HTTP server to expose MCP endpoints over HTTP/SSE. The server will be available on port 8000 by default.

uv run -m bigbugai_mcp.server_http
curl -s http://localhost:8000/healthz

Claude Desktop configuration example

Configure Claude Desktop to connect via the stdio MCP server using environment-based credentials.

{
  "mcpServers": {
    "bigbugai": {
      "command": "uv",
      "args": ["run", "-m", "bigbugai_mcp.server_stdio"],
      "env": {
        "BIGBUGAI_MCP_API_KEY": "your-secret",
        "BTUNIFIED_API": "https://api.bigbug.ai",
        "MCP_RATE_LIMIT": "60/hour"
      }
    }
  }
}

Security and configuration notes

Authentication relies on API keys provided via environment variables. Rate limiting is applied per API key using a moving-window strategy. For security, keep HTTP mode behind an OAuth or reverse proxy when exposed publicly and rotate API keys regularly.

Tests, quality, and tooling

Run unit tests, lint, and type checks to ensure code quality and compatibility with your Python environment.

uv run pytest -q
uv run ruff check .
uv run mypy src

Available tools

get_trending_tokens

Fetches the list of trending tokens, normalized to a flat array of items. Uses a primary API path and falls back to alternatives if needed.

token_analysis_by_contract

Retrieves a report for a specific blockchain contract address and chain, aggregating token intel data.