README.md
A multi-provider MCP server for Tavily, Brave Search, and GrokSearch APIs.
mcp-nexus
English | 中文
mcp-nexus is a robust, multi-provider Model Context Protocol (MCP) server that acts as a bridge for Tavily, Brave Search, and GrokSearch APIs. It provides a unified tool surface, rotating across pools of upstream API keys, all managed through a comprehensive Admin UI.
Features
- Unified Search APIs: Exposes Tavily, Brave, and GrokSearch tools through a single MCP endpoint.
- API Key Management: Easily add, manage, and rotate multiple Tavily, Brave, and Grok API keys to distribute load and handle rate limits.
- Client Authentication: Secure the MCP endpoint with bearer tokens that can be created and revoked via the Admin UI.
- Web Admin UI: A user-friendly interface to manage API keys, client tokens, view usage statistics, and configure server settings.
- Usage Monitoring: Track tool usage, inspect query history, and get summaries of your most used tools and queries.
- Flexible Search Strategy: Dynamically configure source mode (
tavily_only,brave_only,combined, etc.) and key selection strategy (round_robin,random) without restarting the server. - Rate Limiting: Built-in rate limiting for both MCP clients and upstream API calls to prevent abuse and manage costs.
- Flexible Deployment: Run locally with Node.js or deploy anywhere using the provided Docker Compose setup.
Quickstart (Local)
Docker Compose (recommended)
cp .env.example .env
# Edit .env to set your ADMIN_API_TOKEN and other configurations
docker compose up --build
PostgreSQL data is stored in the Docker volume mounted at /var/lib/postgresql/data.
Then open:
- Admin UI:
http://localhost:8787/admin - MCP endpoint:
http://localhost:8787/mcp
Local Node.js
Requires the env vars in .env.example to be set.
npm install
npm run db:bootstrap
npm run dev:bridge-server
Workspace
packages/core: Core logic for Tavily/Brave clients, key management, and MCP tool schemas.packages/bridge-server: The main HTTP server, providing the MCP endpoint and the Admin API/UI.packages/bridge-stdio: A lightweight stdio server for local client integration.packages/stdio-http-bridge: A helper package to connect stdio clients to the HTTP server.packages/db: Prisma schema and database client for all data persistence.packages/admin-ui: The React-based Admin UI frontend.
Admin UI
The Admin UI provides a central place to manage your mcp-nexus instance.
- Keys: Manage upstream Tavily, Brave, and Grok API keys. You can add, remove, update key status (active/disabled/cooldown/invalid), and monitor Tavily credits.
- Tokens: Create and revoke client tokens used to authenticate with the MCP endpoint.
- Usage: View detailed tool usage statistics and query history, with options to filter by date range, tool, and client.
- Settings: Configure live server settings, such as the upstream key selection strategy and the search source mode.
MCP Tools
The server exposes the following tools to MCP clients.
| Tool Name | Provider | Description |
|---|---|---|
tavily_search |
Tavily | Search the web for current information on any topic. Use for news, facts, or data beyond your knowledge cutoff. Returns snippets and source URLs. |
tavily_extract |
Tavily | Extract content from URLs. Returns raw page content in markdown or text format. |
tavily_crawl |
Tavily | Crawl a website starting from a URL. Extracts content from pages with configurable depth and breadth. |
tavily_map |
Tavily | Map a website's structure. Returns a list of URLs found starting from the base URL. |
tavily_research |
Tavily | Perform comprehensive research on a given topic or question. Returns a detailed response based on research findings. |
brave_web_search |
Brave | Performs a web search using the Brave Search API. Use for general web searches for information, facts, and current topics. Returns a JSON array of results. |
brave_local_search |
Brave | Search for local businesses and places using the Brave Search API. Commonly falls back to web search if local results are unavailable. |
Tools (7)
tavily_searchSearch the web for current information on any topic.tavily_extractExtract content from URLs in markdown or text format.tavily_crawlCrawl a website starting from a URL with configurable depth.tavily_mapMap a website's structure to return a list of URLs.tavily_researchPerform comprehensive research on a given topic.brave_web_searchPerforms a web search using the Brave Search API.brave_local_searchSearch for local businesses and places using the Brave Search API.Environment Variables
ADMIN_API_TOKENrequiredToken used for securing the MCP endpoint and Admin UI access.Configuration
claude_desktop_config.json
{"mcpServers": {"mcp-nexus": {"command": "node", "args": ["/path/to/mcp-nexus/dist/index.js"], "env": {"ADMIN_API_TOKEN": "your_token_here"}}}}Try it
→Search for the latest updates on AI regulations using Tavily.
→Find local coffee shops in downtown Seattle using Brave Search.
→Research the current state of quantum computing and summarize the findings.
→Extract the content from this URL to help me summarize the article: [URL]