# ultra-mcp

> MCP Client

**MCP client for enhanced coding tools. Boost Claude, Gemini, Cursor & more with context-aware code generation.**

## Overview

- **Category:** AI
- **Language:** TypeScript
- **Stars:** 274
- **Forks:** 9
- **Owner:** RealMikeChong
- **GitHub:** https://github.com/RealMikeChong/ultra-mcp
- **Created:** 2025-06-28T15:41:40+00:00
- **Updated:** 2025-08-08T10:00:27+00:00
- **Source:** https://model-context-protocol.com/clients/ultra-mcp

## Setup

## Setup

This section outlines the steps to install, configure, and run Ultra MCP.

### Prerequisites

*   **Node.js:** Ensure you have Node.js installed (version 18 or higher recommended). You can download it from [nodejs.org](https://nodejs.org/).
*   **npm:** Node Package Manager (npm) is included with Node.js. Verify it's installed by running `npm -v` in your terminal.

### Installation

You can install Ultra MCP globally using npm or run it directly with npx.

**Option 1: Global Installation (Recommended)**

```bash
npm install -g ultra-mcp
```

This installs Ultra MCP as a global command, making it accessible from any directory in your terminal.

**Option 2: Using npx (No Installation)**

```bash
npx -y ultra-mcp config
```

This runs Ultra MCP directly without installing it globally. The `-y` flag automatically confirms any prompts during installation.

### Configuration

After installation, you need to configure Ultra MCP with your API keys for the AI providers you want to use (OpenAI, Gemini, Azure OpenAI, Grok).

Run the interactive configuration command:

```bash
npx -y ultra-mcp config
```

This command will:

1.  Show the 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 (if required), and preferred models.
4.  Store the configuration securely on your system.
5.  Auto-load settings when the server starts.

**OpenAI-Compatible Support:** The configuration also supports OpenAI-compatible APIs like Ollama (local) or OpenRouter (400+ models).

### Running the Server

Once configured, start the Ultra MCP server:

```bash
npx -y ultra-mcp
```

This will start the MCP server, allowing Claude Code and Cursor to access the configured AI models.

**Alternatively, after building locally:**

```bash
npm run build
node dist/cli.js
```

### Environment Variables

You can also set API keys and base URLs using environment variables. This is useful for automated deployments or when you prefer not to store API keys in a configuration file.

*   `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 settings take 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. You can customize the embedding models in your configuration file (see the original README for details).

## Tools

## Available Tools

- 🤖 **Multi-Model Support**: Integrates OpenAI (O3), Google Gemini (2.5 Pro), Azure OpenAI, and xAI Grok models.
- 🔌 **MCP Protocol**: Provides a standard Model Context Protocol interface for seamless integration with tools like Claude Code and Cursor.
- 🧠 **Deep Reasoning Tools**: Accesses powerful AI models (like O3) for complex problem-solving.
- 🔍 **Investigation & Research**: Offers built-in tools for thorough investigation and research tasks.
- 🌐 **Google Search Integration**: Leverages Gemini 2.5 Pro with real-time web search capabilities.
- ⚡ **Real-time Streaming**: Delivers live model responses via Vercel AI SDK.
- 🔧 **Zero Config**: Enables interactive setup with smart defaults for quick configuration.
- 🔑 **Secure Configuration**: Stores API keys locally using the `conf` library for enhanced security.
- 🧪 **TypeScript**: Ensures full type safety and a modern development experience.

**MCP Tools (Accessible through Claude Code and Cursor):**

### 🧠 Deep Reasoning (`deep-reasoning`)

Leverages advanced AI models for complex problem-solving and analysis.

- **Default**: O3 for OpenAI/Azure, Gemini 2.5 Pro with Google Search, Grok-4 for xAI
- **Use Cases**: Complex algorithms, architectural decisions, deep analysis

```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',
});
```

### 🔍 Investigate (`investigate`)

Thoroughly investigates 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`)

Conducts comprehensive research with multiple output formats.

- **Output Formats**: summary, detailed, academic
- **Use Cases**: Literature reviews, technology comparisons, documentation

### 📋 List Models (`list-ai-models`)

Views all available AI models and their configuration status.