ai-mcp-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ai-mcp-server list models with vision capability"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 / Traeai-mcp ui— local Web management dashboard (FastAPI + Jinja2, bound to 127.0.0.1)
Install
Option 1: uv (recommended)
uv tool install ai-mcp-serverOption 2: Homebrew
brew install brianMacao/tap/ai-mcp-serverOption 3: npm / npx
npx ai-mcp-server # auto-installs uv + Python packageOption 4: pip
pip install ai-mcp-serverRelated 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-serverMCP 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 asaudio_base64inside 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_ttsvolc.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=falseRegister 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:
Call
usage_guide.Use
add_modelswithcapabilitiesfor true capability flags.Use
feature_overridesfor 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 |
| Override data/config directory |
|
| SQLite database path |
|
| Fernet master key for api_key encryption | auto-generated → system keyring |
| Access token for Web UI when exposed ( | 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 -yLicense
MIT
Available Tools
6 toolsadd_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
Scored across 6 tools
Each tool has a clear and distinct purpose: registration, inference, listing, metrics, probing, and guidance. No overlap in functionality.
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.
6 tools is well-scoped for an AI model server, covering registration, inference, listing, performance, probing, and guidance. Not too few or too many.
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
Related MCP Connectors
AI agent registry — search, discover, register, and connect agents via MCP.
MCP server for building and testing AI agents with multi-model experimentation and insights.
Chat, image, video, and audio models from many vendors behind one remote MCP server and one key.
Connect MCP clients to 2,000+ AI models without managing provider API keys.
Related MCP Servers
- FlicenseBqualityCmaintenanceA 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.1075-
- AlicenseNot gradedqualityDmaintenanceMCP 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
- FlicenseNot gradedqualityCmaintenanceEnables 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.-

SandBaseofficial
AlicenseNot gradedqualityBmaintenanceEnables 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 npm186Apache 2.0