Ultra MCP is a Model Context Protocol server that unifies access to multiple AI models (OpenAI, Gemini, Azure, xAI Grok) through a single interface with comprehensive development tools and analytics.
Core Features:
- Unified AI Model Access: Integrates OpenAI, Google Gemini, Azure OpenAI, and xAI Grok models, plus OpenAI-compatible services like Ollama and OpenRouter
- Usage Analytics: Tracks LLM requests, token usage, and costs locally in SQLite database with CLI stats and React-based web dashboard
- Easy Setup: Interactive configuration via
npx ultra-mcp config
and one-command installation for Claude Code/Cursor integration
AI-Powered Development Tools:
- Analysis & Debugging: Deep reasoning, code analysis, code review, issue debugging, and execution tracing
- Research & Investigation: Comprehensive research with multiple output formats and configurable depth levels
- Planning & Documentation: Feature planning, multi-step workflow planning, and documentation generation
- Quality Assurance: Pre-commit validation, security audits with OWASP compliance, and assumption challenging
- Collaboration: Consensus building across multiple AI models for proposals and decisions
- Semantic Search: Vector indexing and natural language search of project files using embeddings
Additional Utilities: Health checks (doctor
), interactive chat, database management, and seamless IDE integration with TypeScript-based architecture for enhanced developer experience.
Uses Drizzle ORM for database interactions with the SQLite usage tracking database
References experience with GitHub Copilot in author background, but no actual integration is provided
Provides access to Google Gemini 2.5 Pro models with real-time web search capabilities for investigation and research
Integrates OpenAI models (including O3) to enable complex problem-solving and reasoning capabilities through a unified MCP interface
Provides a React-based web dashboard for viewing usage statistics and managing configurations
Mentioned as part of the dashboard technology stack for the web UI
Uses local SQLite database (via libSQL) for tracking usage data, token counts and costs of LLM requests
Uses Tailwind CSS for styling the web dashboard interface
Built with TypeScript for full type safety and better developer experience compared to Python-based alternatives
Utilizes Vercel AI SDK for real-time streaming responses from different model providers
Ultra MCP
All Models. One Interface. Zero Friction.
🚀 Ultra MCP - A Model Context Protocol server that exposes OpenAI, Gemini, Azure OpenAI, and xAI Grok AI models through a single MCP interface for use with Claude Code and Cursor.
Stop wasting time having meetings with human. Now it's time to ask AI models do this.
Inspiration
This project is inspired by:
- Agent2Agent (A2A) by Google - Thank you Google for pioneering agent-to-agent communication protocols
- Zen MCP - The AI orchestration server that enables Claude to collaborate with multiple AI models
Why Ultra MCP?
While inspired by zen-mcp-server, Ultra MCP offers several key advantages:
🚀 Easier to Use
- No cloning required - Just run
npx ultra-mcp
to get started - NPM package - Install globally with
npm install -g ultra-mcp
- Interactive setup - Guided configuration with
npx ultra-mcp config
- Zero friction - From zero to AI-powered coding in under a minute
📊 Built-in Usage Analytics
- Local SQLite database - All usage data stored locally using libSQL
- Automatic tracking - Every LLM request is tracked with token counts and costs
- Usage statistics - View your AI usage with
npx ultra-mcp db:stats
- Privacy first - Your data never leaves your machine
🌐 Modern Web Dashboard
- Beautiful UI - React dashboard with Tailwind CSS
- Real-time stats - View usage trends, costs by provider, and model distribution
- Easy access - Just run
npx ultra-mcp dashboard
- Configuration UI - Manage API keys and model priorities from the web
🔧 Additional Benefits
- Simplified tools - Maximum 4 parameters per tool (vs zen's 10-15)
- Smart defaults - Optimal model selection out of the box
- TypeScript first - Full type safety and better developer experience
- Regular updates - Active development with new features weekly
Features
- 🤖 Multi-Model Support: Integrate OpenAI (GPT-5), Google Gemini (2.5 Pro), Azure OpenAI, and xAI Grok models
- 🔌 MCP Protocol: Standard Model Context Protocol interface
- 🧠 Deep Reasoning Tools: Access GPT-5 for complex problem-solving
- 🔍 Investigation & Research: Built-in tools for thorough investigation and research
- 🌐 Google Search Integration: Gemini 2.5 Pro with real-time web search
- ⚡ Real-time Streaming: Live model responses via Vercel AI SDK
- 🔧 Zero Config: Interactive setup with smart defaults
- 🔑 Secure Configuration: Local API key storage with
conf
library - 🧪 TypeScript: Full type safety and modern development experience
Quick Start
Installation
Configuration
Set up your API keys interactively:
This will:
- Show current configuration status
- Present a provider-first menu to select which AI provider to configure
- Guide you through setting API keys, base URLs, and preferred models
- Store configuration securely on your system
- Auto-load settings when the server starts
New in v0.5.10:
- 🎯 Provider-first configuration - Select specific provider to configure
- 🤖 OpenAI-Compatible support - Configure Ollama (local) or OpenRouter (400+ models)
- 📋 Model selection - Choose your preferred model from categorized lists
Running the Server
CLI Commands
Ultra MCP provides several powerful commands:
config
- Interactive Configuration
Configure API keys interactively with a user-friendly menu system.
dashboard
- Web Dashboard
Launch the web dashboard to view usage statistics, manage configurations, and monitor AI costs.
install
- Install for Claude Code
Automatically install Ultra MCP as an MCP server for Claude Code.
doctor
- Health Check
Check installation health and test API connections.
chat
- Interactive Chat
Chat interactively with AI models from the command line.
Database Commands
db:show
- Show Database Info
Display database file location and basic statistics.
db:stats
- Usage Statistics
Show detailed usage statistics for the last 30 days including costs by provider.
db:view
- Database Viewer
Launch Drizzle Studio to explore the usage database interactively.
Integration with Claude Code
Automatic Installation (Recommended)
This command will:
- Detect Claude Code installation
- Add Ultra MCP as an MCP server
- Configure for user or project scope
- Verify API key configuration
Manual Installation
Add to your Claude Code settings:
Integration with Cursor
First configure your API keys:
Then add to your Cursor MCP settings:
Ultra MCP will automatically use the API keys you configured with the config
command.
MCP Tools
Ultra MCP provides powerful AI tools accessible through Claude Code and Cursor:
🧠 Deep Reasoning (deep-reasoning
)
Leverage advanced AI models for complex problem-solving and analysis.
- Default: GPT-5 for OpenAI/Azure, Gemini 2.5 Pro with Google Search, Grok-4 for xAI
- Use Cases: Complex algorithms, architectural decisions, deep analysis
🔍 Investigate (investigate
)
Thoroughly investigate topics with configurable depth levels.
- Depth Levels: shallow, medium, deep
- Google Search: Enabled by default for Gemini
- Use Cases: Research topics, explore concepts, gather insights
📚 Research (research
)
Conduct comprehensive research with multiple output formats.
- Output Formats: summary, detailed, academic
- Use Cases: Literature reviews, technology comparisons, documentation
📋 List Models (list-ai-models
)
View all available AI models and their configuration status.
Example Usage
Development
Architecture
Ultra MCP acts as a bridge between multiple AI model providers and MCP clients:
- MCP Protocol Layer: Implements Model Context Protocol for Claude Code/Cursor communication
- Model Providers: Integrates OpenAI, Google (Gemini), Azure OpenAI, and xAI Grok via Vercel AI SDK
- Unified Interface: Single MCP interface to access multiple AI models
- Configuration Management: Secure local storage with schema validation
Key Components
src/cli.ts
- CLI entry point with commandersrc/server.ts
- MCP server implementationsrc/config/
- Configuration management with schema validationsrc/handlers/
- MCP protocol handlerssrc/providers/
- Model provider implementationssrc/utils/
- Shared utilities for streaming and error handling
Configuration Storage
Ultra MCP stores configuration in your system's default config directory:
- macOS:
~/Library/Preferences/ultra-mcp-nodejs/
- Linux:
~/.config/ultra-mcp/
- Windows:
%APPDATA%\ultra-mcp-nodejs\
Environment Variables
You can also set API keys and base URLs via environment variables:
OPENAI_API_KEY
/OPENAI_BASE_URL
GOOGLE_API_KEY
/GOOGLE_BASE_URL
AZURE_API_KEY
/AZURE_BASE_URL
(base URL required for Azure)XAI_API_KEY
/XAI_BASE_URL
Note: Configuration file takes precedence over environment variables.
Vector Embeddings Configuration
Ultra MCP supports vector embeddings for semantic code search. By default, it uses text-embedding-3-small for cost efficiency (6.5x cheaper than the large model).
Embedding Model Configuration
You can customize the embedding models in your configuration:
Model Comparison
Model | Cost | Dimensions | MTEB Score | Best For |
---|---|---|---|---|
text-embedding-3-small | $0.02/1M tokens | 1536 | 62.3% | Cost-effective code search |
text-embedding-3-large | $0.13/1M tokens | 3072 | 64.6% | Maximum accuracy |
Migration Notes
- Existing Databases: If you have an existing vector database created with
text-embedding-3-large
, it will continue to work but won't be compatible with new embeddings fromtext-embedding-3-small
. Consider re-indexing if you want to use the smaller model. - Backward Compatibility: You can always override the model by configuring
embeddingModel
in your vector config.
Roadmap
Phase 1: Zero Config Setup
- Interactive mode for seamless first-time setup
- Auto-detection of available API keys
- Smart defaults and configuration recommendations
- One-command installation and setup
Phase 2: Integration Helpers
- Helper commands to integrate Ultra MCP into Claude Code
- Cursor IDE integration utilities
- Auto-generation of MCP server configuration files
- Integration validation and troubleshooting tools
Phase 3: Cost Dashboard & Analytics
- Web UI dashboard using React, shadcn/ui, and Tremor
- SQLite database for usage tracking via Drizzle ORM
- Real-time cost monitoring and budget alerts
- Usage analytics and model performance insights
- Export capabilities for billing and reporting
Phase 4: Workflow Optimization
- Use Ultra MCP to 100x your current LLM coding workflows
- Advanced prompt templates and automation
- Multi-model orchestration and fallback strategies
- Workflow optimization recommendations
- Performance monitoring and optimization tools
Contributing
- Fork the repository
- Create a feature branch:
git checkout -b feature-name
- Make your changes and add tests
- Run tests:
npm test
- Commit changes:
git commit -m "Add feature"
- Push to the branch:
git push origin feature-name
- Submit a pull request
Testing
License
MIT License - see LICENSE file for details.
Acknowledgments
- Google for the Agent2Agent (A2A) Protocol inspiring agent interoperability
- BeehiveInnovations for Zen MCP demonstrating AI model orchestration
- Anthropic for the Model Context Protocol
- Vercel for the excellent AI SDK
About the Author
👋 Mike Chong - Building tools to amplify human potential through AI.
As one of the earliest users of GitHub Copilot (personally invited by Nat Friedman, former GitHub CEO), I've witnessed firsthand how AI-assisted development can transform the way we build software. My journey as a former engineer on Outlook iOS/Android taught me the importance of creating tools that genuinely improve people's daily lives.
Ultra MCP represents my vision of democratizing access to the best AI models, making cutting-edge AI capabilities accessible to every developer through a unified, simple interface. I believe that by removing barriers between developers and AI models, we can accelerate innovation and create a better world for everyone.
"The future belongs to those who can seamlessly orchestrate human creativity with AI capabilities."
Why Ultra MCP is Different from Zen MCP Server
While both projects aim to enhance AI development workflows, Ultra MCP brings unique advantages:
- Written in TypeScript - Full type safety, excellent IDE support, and a more maintainable codebase
- Vector Search Support - Built-in semantic code search using vector embeddings
- Index your entire codebase with
npx ultra-mcp index
- Search with natural language queries:
npx ultra-mcp search "authentication logic"
- Powered by OpenAI, Azure OpenAI, and Google Gemini embeddings
- Local SQLite storage with libSQL vector extension for efficient similarity search
- Smart chunking and overlap for optimal search results
- Index your entire codebase with
- Built-in Dashboard & Usage Tracking - Comprehensive analytics and cost monitoring
- Web dashboard with live metrics and real-time statistics
- Automatic tracking of all LLM requests with token counts
- Continuously updated pricing via LiteLLM - Accurate cost calculations
- Tiered pricing support (e.g., Gemini's long-context pricing tiers)
- SQLite database powered by libSQL for local-first privacy
- Advanced Pricing System - Real-time cost management
- Fetches latest pricing from LiteLLM's GitHub repository
- File-based caching with 1-hour TTL to minimize network calls
- CLI commands:
npx ultra-mcp pricing show gpt-4o
- Accurate cost tracking for hundreds of models across all providers
- Automatic fallback to cached data when offline
Unlike many MCP implementations, Ultra MCP includes built-in vector search and a pricing-aware dashboard out of the box. These features make Ultra MCP particularly suited for developers who want robust tooling with built-in cost visibility and intelligent code search capabilities for responsible AI usage.
Links
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
A Model Context Protocol server that exposes OpenAI and Gemini AI models through a single interface, allowing tools like Claude Code and Cursor to access multiple AI providers with built-in usage analytics.
Related MCP Servers
- -securityAlicense-qualityA Model Context Protocol server that enables Claude to collaborate with Google's Gemini AI models, providing tools for question answering, code review, brainstorming, test generation, and explanations.Last updated -PythonMIT License
- -securityFlicense-qualityA Model Context Protocol server that enables Claude to interact with Google's Gemini AI models, allowing users to ask Gemini questions directly from Claude.Last updated -1Python
- -securityFlicense-qualityA Model Context Protocol server that gives Claude access to multiple AI models (Gemini, OpenAI, OpenRouter) for enhanced code analysis, problem-solving, and collaborative development through AI orchestration with conversations that continue across tasks.Last updated -5,958Python
- AsecurityAlicenseAqualityA secure Model Context Protocol server that enables Claude Code to connect with OpenAI and Google Gemini models, allowing users to query multiple AI providers through a standardized interface.Last updated -32JavaScriptMIT License