botrun-default-mcp

A stdio-based MCP (Model Context Protocol) server providing PDF analysis, image analysis, web search, web scraping, and visualization tools. Designed to run via uvx with no server deployment needed.

Tools

Installation

uvx botrun-default-mcp

Or install from source:

git clone https://github.com/sebastian-hsu/botrun_default_mcp_uv.git
cd botrun_default_mcp_uv
uv sync

Configuration

The server automatically loads environment variables from a .env file in the working directory. Just point cwd to the directory containing your .env file — no need to pass env in the MCP config.

LLM routing (chat_with_pdf / chat_with_imgs)

Both tools call Gemini. Which endpoint they use is decided by environment variables (no runtime fallback):

1. BOTRUN_GATE_BASE_URL + BOTRUN_GATE_API_KEY both set → requests go through Botrun Gateway's /gemini/* passthrough (base_url = ${BOTRUN_GATE_BASE_URL}/gemini, auth via Authorization: Bearer). Vertex runs behind the gateway, so no GCP service account is needed. This is the recommended setup.
2. Otherwise → direct Vertex AI with the GOOGLE_APPLICATION_CREDENTIALS_FOR_FASTAPI service account (project scoop-386004, region us-central1).
3. Neither → the tools fail fast with a message naming both options.

Models available through the gateway passthrough are the Vertex gemini-2.5-* family (gemini-2.5-flash, gemini-2.5-pro, gemini-2.5-flash-lite). Aliases such as gemini-flash-latest do not exist there and return 404.

Claude Desktop / Claude Code

Add to your MCP settings (claude_desktop_config.json or .claude.json):

{
  "mcpServers": {
    "botrun-default-mcp": {
      "command": "uvx",
      "args": ["botrun-default-mcp"],
      "cwd": "/path/to/directory/with/dotenv"
    }
  }
}

LangGraph

{
  "botrun-default-mcp": {
    "transport": "stdio",
    "command": "/path/to/uvx",
    "args": ["botrun-default-mcp"],
    "cwd": "/path/to/directory/with/dotenv"
  }
}

.env file example

BOTRUN_GATE_BASE_URL=https://gate.botrun.ai
BOTRUN_GATE_API_KEY=br-your-key-here
OPENROUTER_API_KEY=sk-or-v1-xxx
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
SCRAPERAPI_API_KEY=your-scraperapi-key

Environment Variables

* Either BOTRUN_GATE_BASE_URL + BOTRUN_GATE_API_KEY (recommended) or GOOGLE_APPLICATION_CREDENTIALS_FOR_FASTAPI is required for chat_with_pdf / chat_with_imgs.

† Either PPLX_API_KEY or OPENROUTER_API_KEY + OPENROUTER_BASE_URL is required for web_search.

Development

# Setup
uv sync

# Run tests
uv run pytest tests/ -v

# Build
uv build

# Publish to PyPI
cd sh && bash seba_pypi.sh

License

MIT