ultra-mcp
100x Your Claude Code, Gemini CLI, Cursor and/or any coding tools with MCP client support
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/realmikechong--ultra-mcp)HTML
<a href="/listings/realmikechong--ultra-mcp"><img src="/api/listings/realmikechong--ultra-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Installation
# Install globally via npm npm install -g ultra-mcp # Or run directly with npx npx -y ultra-mcp config
Configuration
Set up your API keys interactively:
npx -y ultra-mcp config
This will:
1. Show current configuration status 2. Present a provider-first menu to select which AI provider to configure 3. Guide you through setting API keys, base URLs, and preferred models 4. Store configuration securely on your system 5. 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
# Run the MCP server npx -y ultra-mcp # Or after building locally bun run build node dist/cli.js
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md Β· README Β· 510 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Ultra MCP
- > **All Models. One Interface. Zero Friction.**
- [](https://badge.fury.io/js/ultra-mcp)
- [](https://www.npmjs.com/package/ultra-mcp)
- π **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)](https://developers.googleblog.com/en/a2a-a-new-era-of-agent-interoperability/)** by Google - Thank you Google for pioneering agent-to-agent communication protocols
- - **[Zen MCP](https://github.com/BeehiveInnovations/zen-mcp-server)** - 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
- - π― **Discoverable Prompts**: All 25 tools available as prompts in Claude Code (New in v0.7.0)
- - π§ **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
- ```bash
- # Install globally via npm
- npm install -g ultra-mcp
- # Or run directly with npx
- npx -y ultra-mcp config
- ```
- ### Configuration
- Set up your API keys interactively:
- ```bash
- npx -y ultra-mcp config
- ```
- This will:
- 1. Show current configuration status
- 2. Present a provider-first menu to select which AI provider to configure
- 3. Guide you through setting API keys, base URLs, and preferred models
- 4. Store configuration securely on your system
- 5. 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
- ```bash
- # Run the MCP server
- npx -y ultra-mcp
- # Or after building locally
- bun run build
- node dist/cli.js
- ```
- ## CLI Commands
- Ultra MCP provides several powerful commands:
- ### `config` - Interactive Configuration
- ```bash
- npx -y ultra-mcp config
- ```
- Configure API keys interactively with a user-friendly menu system.
- ### `dashboard` - Web Dashboard
- ```bash
- npx -y ultra-mcp dashboard
- # Custom port
- npx -y ultra-mcp dashboard --port 4000
- # Development mode
- npx -y ultra-mcp dashboard --dev
- ```
- Launch the web dashboard to view usage statistics, manage configurations, and monitor AI costs.
- ### `install` - Install for Claude Code
- ```bash
- npx -y ultra-mcp install
- ```
- Automatically install Ultra MCP as an MCP server for Claude Code.
- ### `doctor` - Health Check
- ```bash
- npx -y ultra-mcp doctor
- # Test connections to providers
- npx -y ultra-mcp doctor --test
- ```
- Check installation health and test API connections.
- ### `chat` - Interactive Chat
- ```bash
- npx -y ultra-mcp chat
- # Specify model and provider
- npx -y ultra-mcp chat -m gpt-5 -p openai
- npx -y ultra-mcp chat -m grok-4 -p grok
- ```
- Chat interactively with AI models from the command line.
- ### Database Commands
- #### `db:show` - Show Database Info
- ```bash
- npx -y ultra-mcp db:show
- ```
- Display database file location and basic statistics.
- #### `db:stats` - Usage Statistics
- ```bash
- npx -y ultra-mcp db:stats
- ```
- Show detailed usage statistics for the last 30 days including costs by provider.
- #### `db:view` - Database Viewer
- ```bash
- npx -y ultra-mcp db:view
- ```
- Launch Drizzle Studio to explore the usage database interactively.
- ### Integration with Claude Code
- #### Automatic Installation (Recommended)
- ```bash
- # Install Ultra MCP for Claude Code
- npx -y ultra-mcp install
- ```
- 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:
- ```json
- {
- "mcpServers": {
- "ultra-mcp": {
- "command": "npx",
- "args": ["-y", "ultra-mcp@latest"]
- }
- }
- }
- ```
- ### Integration with Cursor
- First configure your API keys:
- ```bash
- npx -y ultra-mcp config
- ```
- Then add to your Cursor MCP settings:
- ```json
- {
- "mcpServers": {
- "ultra-mcp": {
- "command": "npx",
- "args": ["-y", "ultra-mcp@latest"]
- }
- }
- }
- ```
- Ultra MCP will automatically use the API keys you configured with the `config` command.
- ## MCP Tools & Prompts
- Ultra MCP provides powerful AI tools accessible through Claude Code and Cursor. **New in v0.7.0**: All tools are now also available as **discoverable prompts** in Claude Code.
- ### π― Prompts Support (New in v0.7.0)
- All Ultra MCP tools are now exposed as **discoverable prompts** in Claude Code, making them even easier to use:
- - **25 discoverable prompts** corresponding to all existing tools
- - **Parameter guidance** built into each prompt template
- - **Natural language interface** for all AI capabilities
- - **Automatic discovery** by Claude Code and other MCP clients
- **How to use prompts:**
- 1. Type `/` in Claude Code to see available prompts
- 2. Select any Ultra MCP prompt (e.g., "Deep Reasoning", "Code Review", "Debug Issue")
- 3. Fill in the parameters through the guided interface
- 4. Claude automatically generates the appropriate instruction
- This makes Ultra MCP's powerful AI capabilities more accessible than ever!
- ### π§ 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
- ```javascript
- // In Claude Code or Cursor with MCP
- await use_mcp_tool('ultra-mcp', 'deep-reasoning', {
- provider: 'openai',
- prompt: 'Design a distributed caching system for microservices',
- reasoningEffort: 'high',
- });
- ```
- ## Development
- ```bash
- # Clone the repository
- git clone https://github.com/RealMikeChong/ultra-mcp
- cd ultra-mcp
- # Install dependencies
- bun install
- # Build TypeScript
- bun run build
- # Run tests
- bun run test
- # Development mode with watch
- bun run dev
- # Test with MCP Inspector
- npx @modelcontextprotocol/inspector node dist/cli.js
- ```
- ## Architecture
- Ultra MCP acts as a bridge between multiple AI model providers and MCP clients:
- 1. **MCP Protocol Layer**: Implements Model Context Protocol for Claude Code/Cursor communication
- 2. **Model Providers**: Integrates OpenAI, Google (Gemini), Azure OpenAI, and xAI Grok via Vercel AI SDK
- 3. **Unified Interface**: Single MCP interface to access multiple AI models
- 4. **Configuration Management**: Secure local storage with schema validation
- ### Key Components
- - `src/cli.ts` - CLI entry point with commander
- - `src/server.ts` - MCP server implementation
- - `src/config/` - Configuration management with schema validation
- - `src/handlers/` - MCP protocol handlers
- - `src/providers/` - Model provider implementations
- - `src/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:
- ```json
- {
- "vectorConfig": {
- "embeddingModel": {
- "openai": "text-embedding-3-small", // or "text-embedding-3-large"
- "azure": "text-embedding-3-small", // or "text-embedding-3-large"
- "gemini": "text-embedding-004"
- }
- }
- }
- ```
- ### 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 from `text-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
- 1. Fork the repository
- 2. Create a feature branch: `git checkout -b feature-name`
- 3. Make your changes and add tests
- 4. Run tests: `npm test`
- 5. Commit changes: `git commit -m "Add feature"`
- 6. Push to the branch: `git push origin feature-name`
- 7. Submit a pull request
- ## Testing
- ```bash
- # Run all tests
- bun run test
- # Run tests with UI
- bun run test:ui
- # Run tests with coverage
- bun run test:coverage
- ```
- ## License
- MIT License - see [LICENSE](LICENSE) file for details.
- ## Acknowledgments
- - **Google** for the [Agent2Agent (A2A) Protocol](https://developers.googleblog.com/en/a2a-a-new-era-of-agent-interoperability/) inspiring agent interoperability
- - **BeehiveInnovations** for [Zen MCP](https://github.com/BeehiveInnovations/zen-mcp-server) demonstrating AI model orchestration
- - **Anthropic** for the [Model Context Protocol](https://modelcontextprotocol.io/)
- - **Vercel** for the excellent [AI SDK](https://sdk.vercel.ai/)
- ## 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:
- 1. **Written in TypeScript** - Full type safety, excellent IDE support, and a more maintainable codebase
- 2. **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
- 3. **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
- 4. **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
- - [Model Context Protocol](https://modelcontextprotocol.io/)
- - [Agent2Agent Protocol](https://developers.googleblog.com/en/a2a-a-new-era-of-agent-interoperability/)
- - [Zen MCP Server](https://github.com/BeehiveInnovations/zen-mcp-server)
- - [Claude Code](https://claude.ai/code)
- - [Cursor IDE](https://cursor.sh/)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If itβs helped, pass it on.