BigBugAI MCP (Python + FastMCP)

Production-ready MCP server exposing BigBugAI tools with stdio transport for local MCP clients (Claude Desktop, Cursor) and optional HTTP/SSE transport (FastAPI + uvicorn) for remote access.

• Auth via API key (env var)

• Per-key rate limiting (moving window; configurable via env)

• Typed Pydantic schemas for tool I/O

• Clean error handling and JSON-stable outputs

• Tests, ruff, and mypy configuration

Tools

• get_trending_tokens(limit: int = 10) -> list[dict]

  • GET ${BTUNIFIED_API}/api/tokens/newly-ingested by default

  • Falls back to ${BTUNIFIED_API}/v1/trending/tokens and a few other candidates if 404

  • Override primary path with BTUNIFIED_TRENDING_PATH

  • Normalizes {items: [...]} -> [...]

• token_analysis_by_contract(chain: str, address: str) -> dict

  • GET ${BTUNIFIED_API}/api/token-intel/{chain}/{address}/report

Requirements

• Python 3.11+

• Packages: mcp[cli], httpx, pydantic, fastapi, uvicorn, limits, pytest, ruff, mypy

Environment variables

• BIGBUGAI_MCP_API_KEY (required)

• BIGBUGAI_API_KEY / BIGBUGAI_API_TOKEN (optional; used for upstream HTTP calls if set. If not set, HTTP calls will fall back to BIGBUGAI_MCP_API_KEY.)

• BTUNIFIED_API (default: https://api.bigbug.ai)

• MCP_RATE_LIMIT (default: 60/hour, rate string per limits)

Install

Using uv (recommended):

• Unix/macOS

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

• Windows PowerShell

uv venv
.venv\Scripts\Activate.ps1
uv pip install -e .[dev]

Alternatively, you can explicitly add packages (will update pyproject as needed):

uv add "mcp[cli]" httpx pydantic fastapi uvicorn limits pytest ruff mypy

Run (STDIO)

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

Windows PowerShell:

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

This mode is intended for local MCP clients (e.g., Claude Desktop, Cursor).

Note: Tools no longer require api_key in the payload. The server reads the API key from the environment (BIGBUGAI_MCP_API_KEY) and applies rate limiting based on it.

Claude Desktop config

Create claude_desktop_config.json:

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

Run (HTTP)

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

Expected output:

ok

MCP HTTP/SSE endpoints are mounted under /mcp. Depending on your FastMCP version, an SSE stream may be available at /mcp/sse.

Example cURL (SSE; may require -N to keep the connection open and is primarily for debugging):

curl -N http://localhost:8000/mcp/sse

Note: MCP over HTTP/SSE is designed for compatible clients; manual cURL interaction is limited.

Smoke scripts

Quick sanity checks for the tools (require an API key in env):

• Trending

  # uses BIGBUGAI_API_KEY/BIGBUGAI_API_TOKEN/BIGBUGAI_MCP_API_KEY from env
  uv run python scripts/smoke_trending.py -l 5

• Token analysis

  # requires BIGBUGAI_MCP_API_KEY in env; optionally set BB_CHAIN/BB_ADDRESS
  $env:BIGBUGAI_MCP_API_KEY="your-secret"        # PowerShell
  uv run python scripts/smoke_token_analysis.py

Testing and Quality

# Run unit tests
uv run pytest -q

# Lint
uv run ruff check .

# Type check
uv run mypy src

Project layout

bigbugai-mcp/
  .github/workflows/ci.yml
  CODE_OF_CONDUCT.md
  CONTRIBUTING.md
  LICENSE
  README.md
  SECURITY.md
  pyproject.toml
  scripts/list_tools.py
  scripts/smoke_token_analysis.py
  scripts/smoke_trending.py
  src/bigbugai_mcp/__init__.py
  src/bigbugai_mcp/auth.py
  src/bigbugai_mcp/models.py
  src/bigbugai_mcp/server_http.py
  src/bigbugai_mcp/server_stdio.py
  src/bigbugai_mcp/tools.py
  tests/test_tools.py

Security

• Rotate API keys regularly

• Keep HTTP mode behind OAuth/reverse proxy if exposed publicly

• Rate limits are per API key in a moving window strategy

See SECURITY.md for reporting vulnerabilities.

Extending

Add more tools for BigBugAI endpoints (portfolio manager, investment suggester, etc.).

• Add new Pydantic request/response models in src/bigbugai_mcp/models.py

• Add the tool function in src/bigbugai_mcp/tools.py

• Decorate with @guarded and register in register_tools()

• Write tests in tests/

Contributing

Please see CONTRIBUTING.md for guidelines.

Code of Conduct

This project follows the Contributor Covenant.

License

MIT — see LICENSE.