Skip to main content
Glama

ai-mcp-server

Languages: English | 繁體中文 | 简体中文

Local MCP bridge: register multiple (api_key, base_url) pairs once, and let your Agent automatically discover and route to any model with the right capability (chat, vision, reasoning, embedding, image_gen, tts, stt, rerank).

Three entry points:

  • ai-mcp — CLI (manage endpoints, query models, trigger probes, init wizard)

  • ai-mcp-server — MCP stdio server, launched by Claude Desktop / Cursor / Cline / Trae

  • ai-mcp ui — local Web management dashboard (FastAPI + Jinja2, bound to 127.0.0.1)

Install

uv tool install ai-mcp-server

Option 2: Homebrew

brew install brianMacao/tap/ai-mcp-server

Option 3: npm / npx

npx ai-mcp-server      # auto-installs uv + Python package

Option 4: pip

pip install ai-mcp-server

Related MCP server: spiderswitch

Quickstart

# Interactive first-run wizard
ai-mcp init

# Or step by step:
ai-mcp endpoint add --name openrouter --base-url https://openrouter.ai/api/v1 --key sk-...
ai-mcp endpoint probe openrouter
ai-mcp model list --capability vision

# Start the Web UI
ai-mcp ui
# → http://127.0.0.1:8765/

# Start the MCP server (for Claude Desktop, Cursor, etc.)
ai-mcp-server

MCP Tools

ai-mcp-server exposes 6 MCP tools:

  • usage_guide — dynamic inventory, capability distribution, and routing guidance.

  • list_models — filter models by capability, context length, endpoint, and probe state.

  • invoke_model — pass through chat / embedding / image_gen / tts / stt / rerank calls; TTS audio is returned as audio_base64 inside the JSON body.

  • model_performance — inspect recent per-model call counts, success rate, and latency.

  • refresh_endpoint — refresh model lists and enqueue asynchronous capability probes.

  • add_models — manually register models for endpoints without /v1/models, or let an Agent register user-confirmed model features.

Model Feature Registration

Capabilities use canonical names such as text_chat, vision, audio_tts, audio_stt, embedding, and rerank. Common aliases including tts, stt, and asr are accepted by manual registration flows and normalized internally.

Static recognition includes these known model ids:

  • seed-tts-2.0 → audio_tts

  • volc.seedasr.sauc.duration → audio_stt

Register model features from the CLI:

ai-mcp model add --endpoint volc seed-tts-2.0 --capability audio_tts
ai-mcp model add --endpoint volc volc.seedasr.sauc.duration --features asr=true
ai-mcp model add --endpoint volc custom-model --features text_chat=true,context_length=32000
ai-mcp model override volc custom-model --capability vision=false

Register features from the Web UI:

ai-mcp ui
# Open http://127.0.0.1:8765/
# Use Models -> manual add, or Overrides -> add/update feature override.

Register features from an MCP client / Agent:

  1. Call usage_guide.

  2. Use add_models with capabilities for true capability flags.

  3. Use feature_overrides for explicit boolean or context-length overrides.

Example MCP arguments:

{
  "endpoint": "volc",
  "model_ids": ["seed-tts-2.0"],
  "feature_overrides": {
    "audio_tts": true,
    "context_length": 32000
  }
}

Claude Desktop / Trae / Codex Configuration

ai-mcp init will auto-detect installed MCP clients and configure them.

Manual configuration

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "ai-mcp": {
      "command": "uv",
      "args": ["run", "--from", "ai-mcp-server", "ai-mcp-server"]
    }
  }
}

Trae / Trae CN (project root .mcp.json):

{
  "mcpServers": {
    "ai-mcp": {
      "command": "uv",
      "args": ["run", "--from", "ai-mcp-server", "ai-mcp-server"],
      "transport": "stdio"
    }
  }
}

Codex Desktop (~/.codex/config.toml):

[mcp_servers.ai-mcp]
command = "uv"
args = ["run", "--from", "ai-mcp-server", "ai-mcp-server"]

Environment Variables

Variable

Purpose

Default

AI_MCP_CONFIG_DIR

Override data/config directory

~/.ai-mcp-server

AI_MCP_DB_PATH

SQLite database path

$AI_MCP_CONFIG_DIR/db.sqlite3

AI_MCP_MASTER_KEY

Fernet master key for api_key encryption

auto-generated → system keyring

AI_MCP_UI_TOKEN

Access token for Web UI when exposed (--expose)

none

Development

# Clone and set up
git clone https://github.com/brianMacao/ai-mcp-server
cd ai-mcp-server
uv sync

# Run tests
uv run pytest -q

# Verify against real endpoint
cp .keys.example .keys   # edit with your keys
source .keys
export AI_MCP_CONFIG_DIR="$(pwd)/.data"
export AI_MCP_MASTER_KEY="$(cat .data/.master_key)"  # first run generates this
uv run ai-mcp endpoint add --name test --base-url "$EXAMPLE_URL" --key "$EXAMPLE_API_KEY"
uv run ai-mcp endpoint probe test --capability text_chat -y

License

MIT

Available Tools

6 tools
add_modelsA

Manually register models or user-confirmed model features.

Args: endpoint: endpoint name. model_ids: one or more model_id to register. context_length: optional context window in tokens. capabilities: optional capability tags to mark as supported (override source). Aliases tts/stt/asr are accepted. feature_overrides: optional key/value overrides. Keys may be capability tags or context_length; capability values must be booleans. Example: {"audio_tts": true, "context_length": 32000}.

Inputs: endpoint (required), model_ids (required), capabilities, context_length, +1 more. Returns: object

invoke_modelA

Forward a request to the selected (endpoint, model).

Args: endpoint: endpoint name registered via the CLI. model: model_id as returned by list_models. operation: one of chat / embedding / image_gen / tts / stt / rerank. payload: upstream-compatible body (OpenAI shape for openai-compat endpoints). The model field is set automatically. The response is passed through verbatim; errors are returned inside error.

Inputs: model (required), payload (required), endpoint (required), operation (required). Returns: object

list_modelsA

List models matching the filters.

Args: capability: capability tags the model must support (e.g. ["vision"]). min_context_length: minimum context window in tokens. endpoint: limit to a single endpoint name. include_unprobed: include models whose capabilities have not been probed yet (default True).

Inputs: endpoint, capability, include_unprobed, min_context_length. Returns: result

model_performanceB

Return近3天 aggregated call metrics per model (background-updated).

Args: endpoint: limit to a single endpoint name. sort_by: one of call_count / success_count / avg_first_byte_ms / avg_prompt_tokens / avg_output_tokens. limit: max rows to return.

Each row includes call_count, success_count, success_rate, avg_first_byte_ms, avg_prompt_tokens, avg_output_tokens, window_days.

Inputs: limit, sort_by, endpoint. Returns: result

refresh_endpointA

Enqueue probe jobs. Server-internal worker will drain them.

Args: endpoint: endpoint name; if None, refresh every endpoint. capabilities: list of capability tags; if None, choose probes per model using known metadata. refresh_model_list: re-fetch /v1/models first (default True).

Inputs: endpoint, capabilities, refresh_model_list. Returns: object

usage_guideA

Return current capability inventory and usage instructions.

Call this first whenever you connect.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clear and distinct purpose: registration, inference, listing, metrics, probing, and guidance. No overlap in functionality.

    Naming Consistency4/5

    All tools use snake_case, but not all follow verb_noun pattern strictly (e.g., model_performance, usage_guide are noun_noun). Still clear and consistent in style.

    Tool Count5/5

    6 tools is well-scoped for an AI model server, covering registration, inference, listing, performance, probing, and guidance. Not too few or too many.

    Completeness4/5

    Covers core workflows (register, list, invoke, metrics, update via probe, guidance). Missing explicit delete or update tool for models, but add_models can override features, partially filling that gap.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      B
      quality
      C
      maintenance
      A bridge that enables seamless integration of Ollama's local LLM capabilities into MCP-powered applications, allowing users to manage and run AI models locally with full API coverage.
      10
      75
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that enables agents to dynamically switch between multiple AI models (OpenAI, Anthropic, Google, etc.) with unified protocol-driven configuration and capability discovery.
      Apache 2.0
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables agents to discover, evaluate, and serve task-specialist models (embeddings, reranking, classification, extraction) with OpenAI-compatible endpoints and MCP tools for routing, embedding, reranking, and extraction.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to discover and invoke 2,000+ models and APIs—including web search, social media, scraping, image/video generation, and audio—through a single local MCP bridge using OAuth, with no per-API keys.
      295 npm
      186
      Apache 2.0