MCP Bridge Server

Token-efficient Model Context Protocol aggregator - Reduce MCP token overhead by 95%+

⚡ Quick Setup: Only need TAVILY_API_KEY - See SIMPLE_SETUP.md

The Problem

Using multiple MCP servers directly with Claude Code creates massive token overhead:

Serena (23 tools)    → ~23,000 tokens
Playwright (21 tools) → ~21,000 tokens
shadcn (7 tools)     → ~7,000 tokens
Tavily (4 tools)     → ~4,000 tokens
Context7 (2 tools)   → ~2,000 tokens
────────────────────────────────────
Total                → ~57,000 tokens 😱

This consumes your context window before you even start working!

The Solution

MCP Bridge aggregates all downstream servers into 5-6 category-based tools:

code_operations         → All 23 Serena tools
documentation_lookup    → All 2 Context7 tools
browser_testing         → All 21 Playwright tools
web_research           → All 4 Tavily tools
ui_components          → All 7 shadcn tools
batch_operations       → Parallel execution
────────────────────────────────────
Total                  → ~1,800 tokens ✨ (97% reduction)

Quick Start

Option 1: Remote (Recommended)

No installation needed! Just one environment variable required:

// ~/.claude.json
{
  "mcpServers": {
    "mcp-bridge": {
      "command": "npx",
      "args": ["mcp-bridge@latest"],
      "env": {
        "TAVILY_API_KEY": "tvly-dev-your-key-here"
      }
    }
  }
}

Get your free Tavily API key at https://tavily.com

That's it! All 5 MCP servers (57 tools) enabled by default.

📖 See SIMPLE_SETUP.md for details and optional configuration

Option 2: Local Development

# Clone and install
git clone https://github.com/yourusername/mcp-bridge.git
cd mcp-bridge
npm install

# Configure environment
cp .env.example .env
# Edit .env and add your TAVILY_API_KEY (required)
# All MCP servers enabled by default

# Build and run
npm run build
npm start

# Add to ~/.claude.json
{
  "mcpServers": {
    "mcp-bridge": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-bridge/dist/index.js"]
    }
  }
}

Features

✨ 95%+ Token Reduction - 57k → 1.8k tokens ⚡ Smart Caching - TTL-based with auto-invalidation 🚀 Parallel Execution - Batch operations with concurrency control 🔄 Auto-Retry - Exponential backoff for transient failures 📊 Real-time Metrics - Token usage and performance tracking 🎯 Response Compression - Automatic output optimization 🎨 UI Components - shadcn/ui integration with registry management

Usage Example

Traditional MCP (Inefficient)

// Multiple sequential calls, high token overhead
await findSymbol({ name: "User" });
await findSymbol({ name: "Post" });
await getLibraryDocs({ library: "react" });

MCP Bridge (Efficient)

// Single batch call, parallel execution
{
  name: "batch_operations",
  arguments: {
    operations: [
      { category: "code_operations", operation: "findSymbol", params: { name_path: "User" } },
      { category: "code_operations", operation: "findSymbol", params: { name_path: "Post" } },
      { category: "documentation_lookup", operation: "getLibraryDocs", params: { library_id: "react" } }
    ]
  }
}

Architecture

┌─────────────────────────────┐
│      Claude Code Agent      │  (Sees only 4-5 tools)
└──────────────┬──────────────┘
               │ ~1.5k tokens
┌──────────────▼──────────────┐
│      MCP Bridge Server      │
│  • Smart routing            │
│  • Caching & compression    │
│  • Parallel execution       │
│  • Error handling           │
└──┬─────┬─────┬─────┬────────┘
   │     │     │     │
   ▼     ▼     ▼     ▼
┌─────┐┌───┐┌────┐┌──────┐
│Serena││C7 ││Play││Tavily│  50 downstream tools
└─────┘└───┘└────┘└──────┘

Documentation

• Complete API Reference
• Usage Examples
• Full Documentation

Bridge Tools

🔧 code_operations (Serena)

Code analysis, editing, memory, and project operations

• Search: findSymbol, findFiles, searchInFiles
• Edit: editFile, writeFile, createFile
• Memory: readMemory, writeMemory, listMemories
• Project: getProjectStructure, analyzeProject

📚 documentation_lookup (Context7)

Official library documentation queries

• Docs: resolveLibraryId, getLibraryDocs

🌐 browser_testing (Playwright)

Browser automation and testing

• Navigation: navigate, goBack, goForward
• Interaction: click, fill, select
• Inspection: takeSnapshot, screenshot

🔍 web_research (Tavily)

Web search and content extraction

• Research: search, extract, crawl, map

⚡ batch_operations

Execute multiple operations in parallel

Performance

| Metric | Value | |--------|-------| | Token Reduction | 97% (50k → 1.5k) | | Cache Hit Rate | 40-60% (read ops) | | Parallel Speedup | 60-80% (batch ops) | | Latency Overhead | ~10-20ms (uncached) |

Configuration

Key environment variables:

TAVILY_API_KEY=tvly-dev-xxx          # Required for Tavily
CACHE_ENABLED=true                    # Enable caching
CACHE_TTL_SECONDS=300                 # 5 minute TTL
MAX_CONCURRENT_OPERATIONS=10          # Parallel limit
METRICS_ENABLED=true                  # Track metrics

See .env.example for complete configuration.

Development

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Development mode
npm run dev

# Lint and format
npm run lint
npm run format

Requirements

• Node.js ≥ 18.0.0
• Downstream servers:
  • Serena: uvx --from git+https://github.com/oraios/serena
  • Context7: npx -y @upstash/context7-mcp
  • Playwright: npx -y @playwright/mcp
  • Tavily: npx -y tavily-mcp@latest (requires API key)

Monitoring

View real-time dashboard:

╔════════════════════════════════════════════════════════════════╗
║                    MCP Bridge Dashboard                        ║
╚════════════════════════════════════════════════════════════════╝

📊 Operations
   Total: 150
   Successful: 147 (98.0%)
   Avg Duration: 245.32ms

🎯 Token Efficiency
   Bridge Tokens: 2,450
   Direct MCP Est: 75,000
   Reduction: 96.7%

💾 Cache
   Size: 45/1000
   Hit Rate: 52.3%

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass (npm test)
5. Submit a pull request

License

MIT License - see LICENSE for details

Credits

Inspired by Anthropic's Code Execution with MCP

Built with:

• @modelcontextprotocol/sdk
• Serena
• Playwright MCP
• Tavily
• Context7

Support

• 📖 Documentation
• 💬 Issues
• 🌟 Star on GitHub

Made with ❤️ for the MCP community