Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/realmikechong--ultra-mcp/badge.svg)](/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

i

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)

  1. # Ultra MCP
  2. > **All Models. One Interface. Zero Friction.**
  3. [![npm version](https://badge.fury.io/js/ultra-mcp.svg)](https://badge.fury.io/js/ultra-mcp)
  4. [![npm downloads](https://img.shields.io/npm/dm/ultra-mcp.svg)](https://www.npmjs.com/package/ultra-mcp)
  5. πŸš€ **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.
  6. ![img](https://github.com/user-attachments/assets/b2ade474-7c68-458c-84e4-daa73e32ad8c)
  7. > Stop wasting time having meetings with human. Now it's time to ask AI models do this.
  8. ## Inspiration
  9. This project is inspired by:
  10. - **[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
  11. - **[Zen MCP](https://github.com/BeehiveInnovations/zen-mcp-server)** - The AI orchestration server that enables Claude to collaborate with multiple AI models
  12. ## Why Ultra MCP?
  13. While inspired by zen-mcp-server, Ultra MCP offers several key advantages:
  14. ### πŸš€ **Easier to Use**
  15. - **No cloning required** - Just run `npx ultra-mcp` to get started
  16. - **NPM package** - Install globally with `npm install -g ultra-mcp`
  17. - **Interactive setup** - Guided configuration with `npx ultra-mcp config`
  18. - **Zero friction** - From zero to AI-powered coding in under a minute
  19. ### πŸ“Š **Built-in Usage Analytics**
  20. - **Local SQLite database** - All usage data stored locally using libSQL
  21. - **Automatic tracking** - Every LLM request is tracked with token counts and costs
  22. - **Usage statistics** - View your AI usage with `npx ultra-mcp db:stats`
  23. - **Privacy first** - Your data never leaves your machine
  24. ### 🌐 **Modern Web Dashboard**
  25. - **Beautiful UI** - React dashboard with Tailwind CSS
  26. - **Real-time stats** - View usage trends, costs by provider, and model distribution
  27. - **Easy access** - Just run `npx ultra-mcp dashboard`
  28. - **Configuration UI** - Manage API keys and model priorities from the web
  29. ### πŸ”§ **Additional Benefits**
  30. - **Simplified tools** - Maximum 4 parameters per tool (vs zen's 10-15)
  31. - **Smart defaults** - Optimal model selection out of the box
  32. - **TypeScript first** - Full type safety and better developer experience
  33. - **Regular updates** - Active development with new features weekly
  34. ## Features
  35. - πŸ€– **Multi-Model Support**: Integrate OpenAI (GPT-5), Google Gemini (2.5 Pro), Azure OpenAI, and xAI Grok models
  36. - πŸ”Œ **MCP Protocol**: Standard Model Context Protocol interface
  37. - 🎯 **Discoverable Prompts**: All 25 tools available as prompts in Claude Code (New in v0.7.0)
  38. - 🧠 **Deep Reasoning Tools**: Access GPT-5 for complex problem-solving
  39. - πŸ” **Investigation & Research**: Built-in tools for thorough investigation and research
  40. - 🌐 **Google Search Integration**: Gemini 2.5 Pro with real-time web search
  41. - ⚑ **Real-time Streaming**: Live model responses via Vercel AI SDK
  42. - πŸ”§ **Zero Config**: Interactive setup with smart defaults
  43. - πŸ”‘ **Secure Configuration**: Local API key storage with `conf` library
  44. - πŸ§ͺ **TypeScript**: Full type safety and modern development experience
  45. ## Quick Start
  46. ### Installation
  47. ```bash
  48. # Install globally via npm
  49. npm install -g ultra-mcp
  50. # Or run directly with npx
  51. npx -y ultra-mcp config
  52. ```
  53. ### Configuration
  54. Set up your API keys interactively:
  55. ```bash
  56. npx -y ultra-mcp config
  57. ```
  58. This will:
  59. 1. Show current configuration status
  60. 2. Present a provider-first menu to select which AI provider to configure
  61. 3. Guide you through setting API keys, base URLs, and preferred models
  62. 4. Store configuration securely on your system
  63. 5. Auto-load settings when the server starts
  64. **New in v0.5.10:**
  65. - 🎯 **Provider-first configuration** - Select specific provider to configure
  66. - πŸ€– **OpenAI-Compatible support** - Configure Ollama (local) or OpenRouter (400+ models)
  67. - πŸ“‹ **Model selection** - Choose your preferred model from categorized lists
  68. ### Running the Server
  69. ```bash
  70. # Run the MCP server
  71. npx -y ultra-mcp
  72. # Or after building locally
  73. bun run build
  74. node dist/cli.js
  75. ```
  76. ## CLI Commands
  77. Ultra MCP provides several powerful commands:
  78. ### `config` - Interactive Configuration
  79. ```bash
  80. npx -y ultra-mcp config
  81. ```
  82. Configure API keys interactively with a user-friendly menu system.
  83. ### `dashboard` - Web Dashboard
  84. ```bash
  85. npx -y ultra-mcp dashboard
  86. # Custom port
  87. npx -y ultra-mcp dashboard --port 4000
  88. # Development mode
  89. npx -y ultra-mcp dashboard --dev
  90. ```
  91. Launch the web dashboard to view usage statistics, manage configurations, and monitor AI costs.
  92. ### `install` - Install for Claude Code
  93. ```bash
  94. npx -y ultra-mcp install
  95. ```
  96. Automatically install Ultra MCP as an MCP server for Claude Code.
  97. ### `doctor` - Health Check
  98. ```bash
  99. npx -y ultra-mcp doctor
  100. # Test connections to providers
  101. npx -y ultra-mcp doctor --test
  102. ```
  103. Check installation health and test API connections.
  104. ### `chat` - Interactive Chat
  105. ```bash
  106. npx -y ultra-mcp chat
  107. # Specify model and provider
  108. npx -y ultra-mcp chat -m gpt-5 -p openai
  109. npx -y ultra-mcp chat -m grok-4 -p grok
  110. ```
  111. Chat interactively with AI models from the command line.
  112. ### Database Commands
  113. #### `db:show` - Show Database Info
  114. ```bash
  115. npx -y ultra-mcp db:show
  116. ```
  117. Display database file location and basic statistics.
  118. #### `db:stats` - Usage Statistics
  119. ```bash
  120. npx -y ultra-mcp db:stats
  121. ```
  122. Show detailed usage statistics for the last 30 days including costs by provider.
  123. #### `db:view` - Database Viewer
  124. ```bash
  125. npx -y ultra-mcp db:view
  126. ```
  127. Launch Drizzle Studio to explore the usage database interactively.
  128. ### Integration with Claude Code
  129. #### Automatic Installation (Recommended)
  130. ```bash
  131. # Install Ultra MCP for Claude Code
  132. npx -y ultra-mcp install
  133. ```
  134. This command will:
  135. - Detect Claude Code installation
  136. - Add Ultra MCP as an MCP server
  137. - Configure for user or project scope
  138. - Verify API key configuration
  139. #### Manual Installation
  140. Add to your Claude Code settings:
  141. ```json
  142. {
  143. "mcpServers": {
  144. "ultra-mcp": {
  145. "command": "npx",
  146. "args": ["-y", "ultra-mcp@latest"]
  147. }
  148. }
  149. }
  150. ```
  151. ### Integration with Cursor
  152. First configure your API keys:
  153. ```bash
  154. npx -y ultra-mcp config
  155. ```
  156. Then add to your Cursor MCP settings:
  157. ```json
  158. {
  159. "mcpServers": {
  160. "ultra-mcp": {
  161. "command": "npx",
  162. "args": ["-y", "ultra-mcp@latest"]
  163. }
  164. }
  165. }
  166. ```
  167. Ultra MCP will automatically use the API keys you configured with the `config` command.
  168. ## MCP Tools & Prompts
  169. 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.
  170. ### 🎯 Prompts Support (New in v0.7.0)
  171. All Ultra MCP tools are now exposed as **discoverable prompts** in Claude Code, making them even easier to use:
  172. - **25 discoverable prompts** corresponding to all existing tools
  173. - **Parameter guidance** built into each prompt template
  174. - **Natural language interface** for all AI capabilities
  175. - **Automatic discovery** by Claude Code and other MCP clients
  176. **How to use prompts:**
  177. 1. Type `/` in Claude Code to see available prompts
  178. 2. Select any Ultra MCP prompt (e.g., "Deep Reasoning", "Code Review", "Debug Issue")
  179. 3. Fill in the parameters through the guided interface
  180. 4. Claude automatically generates the appropriate instruction
  181. This makes Ultra MCP's powerful AI capabilities more accessible than ever!
  182. ### 🧠 Deep Reasoning (`deep-reasoning`)
  183. Leverage advanced AI models for complex problem-solving and analysis.
  184. - **Default**: GPT-5 for OpenAI/Azure, Gemini 2.5 Pro with Google Search, Grok-4 for xAI
  185. - **Use Cases**: Complex algorithms, architectural decisions, deep analysis
  186. ### πŸ” Investigate (`investigate`)
  187. Thoroughly investigate topics with configurable depth levels.
  188. - **Depth Levels**: shallow, medium, deep
  189. - **Google Search**: Enabled by default for Gemini
  190. - **Use Cases**: Research topics, explore concepts, gather insights
  191. ### πŸ“š Research (`research`)
  192. Conduct comprehensive research with multiple output formats.
  193. - **Output Formats**: summary, detailed, academic
  194. - **Use Cases**: Literature reviews, technology comparisons, documentation
  195. ### πŸ“‹ List Models (`list-ai-models`)
  196. View all available AI models and their configuration status.
  197. ### Example Usage
  198. ```javascript
  199. // In Claude Code or Cursor with MCP
  200. await use_mcp_tool('ultra-mcp', 'deep-reasoning', {
  201. provider: 'openai',
  202. prompt: 'Design a distributed caching system for microservices',
  203. reasoningEffort: 'high',
  204. });
  205. ```
  206. ## Development
  207. ```bash
  208. # Clone the repository
  209. git clone https://github.com/RealMikeChong/ultra-mcp
  210. cd ultra-mcp
  211. # Install dependencies
  212. bun install
  213. # Build TypeScript
  214. bun run build
  215. # Run tests
  216. bun run test
  217. # Development mode with watch
  218. bun run dev
  219. # Test with MCP Inspector
  220. npx @modelcontextprotocol/inspector node dist/cli.js
  221. ```
  222. ## Architecture
  223. Ultra MCP acts as a bridge between multiple AI model providers and MCP clients:
  224. 1. **MCP Protocol Layer**: Implements Model Context Protocol for Claude Code/Cursor communication
  225. 2. **Model Providers**: Integrates OpenAI, Google (Gemini), Azure OpenAI, and xAI Grok via Vercel AI SDK
  226. 3. **Unified Interface**: Single MCP interface to access multiple AI models
  227. 4. **Configuration Management**: Secure local storage with schema validation
  228. ### Key Components
  229. - `src/cli.ts` - CLI entry point with commander
  230. - `src/server.ts` - MCP server implementation
  231. - `src/config/` - Configuration management with schema validation
  232. - `src/handlers/` - MCP protocol handlers
  233. - `src/providers/` - Model provider implementations
  234. - `src/utils/` - Shared utilities for streaming and error handling
  235. ## Configuration Storage
  236. Ultra MCP stores configuration in your system's default config directory:
  237. - **macOS**: `~/Library/Preferences/ultra-mcp-nodejs/`
  238. - **Linux**: `~/.config/ultra-mcp/`
  239. - **Windows**: `%APPDATA%\ultra-mcp-nodejs\`
  240. ## Environment Variables
  241. You can also set API keys and base URLs via environment variables:
  242. - `OPENAI_API_KEY` / `OPENAI_BASE_URL`
  243. - `GOOGLE_API_KEY` / `GOOGLE_BASE_URL`
  244. - `AZURE_API_KEY` / `AZURE_BASE_URL` (base URL required for Azure)
  245. - `XAI_API_KEY` / `XAI_BASE_URL`
  246. _Note: Configuration file takes precedence over environment variables._
  247. ## Vector Embeddings Configuration
  248. 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).
  249. ### Embedding Model Configuration
  250. You can customize the embedding models in your configuration:
  251. ```json
  252. {
  253. "vectorConfig": {
  254. "embeddingModel": {
  255. "openai": "text-embedding-3-small", // or "text-embedding-3-large"
  256. "azure": "text-embedding-3-small", // or "text-embedding-3-large"
  257. "gemini": "text-embedding-004"
  258. }
  259. }
  260. }
  261. ```
  262. ### Model Comparison
  263. | Model | Cost | Dimensions | MTEB Score | Best For |
  264. |-------|------|------------|------------|----------|
  265. | text-embedding-3-small | $0.02/1M tokens | 1536 | 62.3% | Cost-effective code search |
  266. | text-embedding-3-large | $0.13/1M tokens | 3072 | 64.6% | Maximum accuracy |
  267. ### Migration Notes
  268. - **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.
  269. - **Backward Compatibility**: You can always override the model by configuring `embeddingModel` in your vector config.
  270. ## Roadmap
  271. ### Phase 1: Zero Config Setup
  272. - Interactive mode for seamless first-time setup
  273. - Auto-detection of available API keys
  274. - Smart defaults and configuration recommendations
  275. - One-command installation and setup
  276. ### Phase 2: Integration Helpers
  277. - Helper commands to integrate Ultra MCP into Claude Code
  278. - Cursor IDE integration utilities
  279. - Auto-generation of MCP server configuration files
  280. - Integration validation and troubleshooting tools
  281. ### Phase 3: Cost Dashboard & Analytics
  282. - Web UI dashboard using React, shadcn/ui, and Tremor
  283. - SQLite database for usage tracking via Drizzle ORM
  284. - Real-time cost monitoring and budget alerts
  285. - Usage analytics and model performance insights
  286. - Export capabilities for billing and reporting
  287. ### Phase 4: Workflow Optimization
  288. - Use Ultra MCP to 100x your current LLM coding workflows
  289. - Advanced prompt templates and automation
  290. - Multi-model orchestration and fallback strategies
  291. - Workflow optimization recommendations
  292. - Performance monitoring and optimization tools
  293. ## Contributing
  294. 1. Fork the repository
  295. 2. Create a feature branch: `git checkout -b feature-name`
  296. 3. Make your changes and add tests
  297. 4. Run tests: `npm test`
  298. 5. Commit changes: `git commit -m "Add feature"`
  299. 6. Push to the branch: `git push origin feature-name`
  300. 7. Submit a pull request
  301. ## Testing
  302. ```bash
  303. # Run all tests
  304. bun run test
  305. # Run tests with UI
  306. bun run test:ui
  307. # Run tests with coverage
  308. bun run test:coverage
  309. ```
  310. ## License
  311. MIT License - see [LICENSE](LICENSE) file for details.
  312. ## Acknowledgments
  313. - **Google** for the [Agent2Agent (A2A) Protocol](https://developers.googleblog.com/en/a2a-a-new-era-of-agent-interoperability/) inspiring agent interoperability
  314. - **BeehiveInnovations** for [Zen MCP](https://github.com/BeehiveInnovations/zen-mcp-server) demonstrating AI model orchestration
  315. - **Anthropic** for the [Model Context Protocol](https://modelcontextprotocol.io/)
  316. - **Vercel** for the excellent [AI SDK](https://sdk.vercel.ai/)
  317. ## About the Author
  318. πŸ‘‹ **Mike Chong** - Building tools to amplify human potential through AI.
  319. 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.
  320. **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.
  321. _"The future belongs to those who can seamlessly orchestrate human creativity with AI capabilities."_
  322. ## Why Ultra MCP is Different from Zen MCP Server
  323. While both projects aim to enhance AI development workflows, Ultra MCP brings unique advantages:
  324. 1. **Written in TypeScript** - Full type safety, excellent IDE support, and a more maintainable codebase
  325. 2. **Vector Search Support** - Built-in semantic code search using vector embeddings
  326. - Index your entire codebase with `npx ultra-mcp index`
  327. - Search with natural language queries: `npx ultra-mcp search "authentication logic"`
  328. - Powered by OpenAI, Azure OpenAI, and Google Gemini embeddings
  329. - Local SQLite storage with libSQL vector extension for efficient similarity search
  330. - Smart chunking and overlap for optimal search results
  331. 3. **Built-in Dashboard & Usage Tracking** - Comprehensive analytics and cost monitoring
  332. - Web dashboard with live metrics and real-time statistics
  333. - Automatic tracking of all LLM requests with token counts
  334. - **Continuously updated pricing via LiteLLM** - Accurate cost calculations
  335. - Tiered pricing support (e.g., Gemini's long-context pricing tiers)
  336. - SQLite database powered by libSQL for local-first privacy
  337. 4. **Advanced Pricing System** - Real-time cost management
  338. - Fetches latest pricing from LiteLLM's GitHub repository
  339. - File-based caching with 1-hour TTL to minimize network calls
  340. - CLI commands: `npx ultra-mcp pricing show gpt-4o`
  341. - Accurate cost tracking for hundreds of models across all providers
  342. - Automatic fallback to cached data when offline
  343. 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.
  344. ## Links
  345. - [Model Context Protocol](https://modelcontextprotocol.io/)
  346. - [Agent2Agent Protocol](https://developers.googleblog.com/en/a2a-a-new-era-of-agent-interoperability/)
  347. - [Zen MCP Server](https://github.com/BeehiveInnovations/zen-mcp-server)
  348. - [Claude Code](https://claude.ai/code)
  349. - [Cursor IDE](https://cursor.sh/)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.