# MCP Nexus - Cloudflare Workers
[](https://deploy.workers.cloudflare.com/?url=https://github.com/ykq007/mcp-nexus/tree/main/packages/worker)
One-click deployment of MCP Nexus to Cloudflare's free tier. This provides a unified MCP server for Tavily and Brave Search APIs with automatic API key rotation.
## Features
- **Zero-cost hosting** on Cloudflare Workers free tier
- **D1 Database** for persistent storage (automatic provisioning)
- **Encrypted API keys** with Web Crypto API
- **Admin UI included** - Full web interface for managing keys and tokens
- **7 MCP tools**: tavily_search, tavily_extract, tavily_crawl, tavily_map, tavily_research, brave_web_search, brave_local_search
## Deploy
### Option 1: One-Click Deploy
Click the button above and follow the prompts. You'll be asked to:
1. Authorize Cloudflare to access your GitHub (fork will be created)
2. Configure secrets:
- `ADMIN_API_TOKEN`: Token for admin API access (generate with `openssl rand -hex 32`)
- `KEY_ENCRYPTION_SECRET`: Key for encrypting API keys (generate with `openssl rand -base64 32`)
### Option 2: Manual Deploy
```bash
# Clone the repo
git clone https://github.com/ykq007/mcp-nexus.git
cd mcp-nexus/packages/worker
# Install dependencies
npm install
# Create D1 database
npx wrangler d1 create mcp-nexus-db
# Copy the database_id from output to wrangler.jsonc
# Set secrets
npx wrangler secret put ADMIN_API_TOKEN
npx wrangler secret put KEY_ENCRYPTION_SECRET
# Run migrations and deploy
npm run deploy
```
## Post-Deployment Setup
After deployment, you need to add API keys and create client tokens.
### 1. Add Tavily API Keys
```bash
curl -X POST https://your-worker.workers.dev/admin/api/tavily-keys \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"label": "Primary Key", "key": "tvly-xxxxx"}'
```
### 2. Add Brave API Keys (Optional)
```bash
curl -X POST https://your-worker.workers.dev/admin/api/brave-keys \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"label": "Primary Key", "key": "BSAxxxxx"}'
```
### 3. Create Client Token
```bash
curl -X POST https://your-worker.workers.dev/admin/api/tokens \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"description": "Claude Desktop"}'
```
Save the returned `token` - it's only shown once.
## MCP Client Configuration
### Claude Desktop / Cline
```json
{
"mcpServers": {
"mcp-nexus": {
"command": "npx",
"args": ["-y", "@anthropic-ai/mcp-proxy", "https://your-worker.workers.dev/mcp"],
"env": {
"MCP_HEADERS": "Authorization: Bearer YOUR_CLIENT_TOKEN"
}
}
}
}
```
### Direct HTTP
```bash
curl -X POST https://your-worker.workers.dev/mcp \
-H "Authorization: Bearer YOUR_CLIENT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "tools/list",
"id": 1
}'
```
## API Endpoints
| Endpoint | Auth | Description |
|----------|------|-------------|
| `POST /mcp` | Client Token | MCP JSON-RPC endpoint |
| `GET /health` | None | Health check |
| `GET /admin/api/tavily-keys` | Admin Token | List Tavily keys |
| `POST /admin/api/tavily-keys` | Admin Token | Add Tavily key |
| `DELETE /admin/api/tavily-keys/:id` | Admin Token | Delete Tavily key |
| `GET /admin/api/brave-keys` | Admin Token | List Brave keys |
| `POST /admin/api/brave-keys` | Admin Token | Add Brave key |
| `DELETE /admin/api/brave-keys/:id` | Admin Token | Delete Brave key |
| `GET /admin/api/tokens` | Admin Token | List client tokens |
| `POST /admin/api/tokens` | Admin Token | Create client token |
| `DELETE /admin/api/tokens/:id` | Admin Token | Revoke client token |
| `GET /admin/api/settings` | Admin Token | Get settings |
| `PUT /admin/api/settings` | Admin Token | Update settings |
| `GET /admin/api/usage` | Admin Token | View usage logs |
## Local Development
```bash
# Install dependencies
npm install
# Create local D1 database
npm run db:migrate:local
# Start dev server
npm run dev
```
## Architecture
```
┌─────────────────────────────────────────────────────────┐
│ Cloudflare Workers │
├─────────────────────────────────────────────────────────┤
│ Hono Router │
│ ├── /mcp (MCP JSON-RPC) │
│ ├── /admin/api/* (Admin API) │
│ └── /health │
├─────────────────────────────────────────────────────────┤
│ Services │
│ ├── Key Pool (rotation, cooldown) │
│ ├── Tavily Client │
│ └── Brave Client │
├─────────────────────────────────────────────────────────┤
│ D1 Database │
│ ├── tavily_keys (encrypted) │
│ ├── brave_keys (encrypted) │
│ ├── client_tokens (hashed) │
│ ├── server_settings │
│ └── usage_logs │
└─────────────────────────────────────────────────────────┘
```
## License
MIT
