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-ingestedby default - Falls back to
${BTUNIFIED_API}/v1/trending/tokensand a few other candidates if 404 - Override primary path with
BTUNIFIED_TRENDING_PATH - Normalizes
{items: [...]} -> [...]
- GET
token_analysis_by_contract(chain: str, address: str) -> dict- GET
${BTUNIFIED_API}/api/token-intel/{chain}/{address}/report
- GET
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 toBIGBUGAI_MCP_API_KEY.)BTUNIFIED_API(default:https://api.bigbug.ai)MCP_RATE_LIMIT(default:60/hour, rate string perlimits)
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
@guardedand register inregister_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.