MCP客户端

Requirements

• Python 3.10+ (Installation guide)
• Ollama running locally (Installation guide)
• UV package manager (Installation guide)

Quick Start

Option 1: Install with pip and run

pip install --upgrade ollmcp
ollmcp

Option 2: One-step install and run

uvx ollmcp

Option 3: Install from source and run using virtual environment

git clone https://github.com/jonigl/mcp-client-for-ollama.git
cd mcp-client-for-ollama
uv venv && source .venv/bin/activate
uv pip install .
uv run -m mcp_client_for_ollama

Usage

Run with default settings:

ollmcp

If you don't provide any options, the client will use auto-discovery mode to find MCP servers from Claude's configuration.

Usage Examples

Simplest way to run the client:

ollmcp

Connect to a single server:

```bash ollmcp --mcp-server /path/to/weather.py --model llama3.2:3b

Tips: where to put MCP server configs and a working example

A common point of confusion is where to store MCP server configuration files and how the TUI's save/load feature is used. Here's a short, practical guide that has helped other users:

• The TUI's save-config / load-config (or sc / lc) commands are intended to save TUI preferences like which tools you enabled, your selected model, thinking mode, display mode, and other client-side settings. They are not required to register MCP server connections with the client.
• For MCP server JSON files (the mcpServers object shown above) we recommend keeping them outside the TUI config directory or in a clear subfolder, for example:

~/.config/ollmcp/mcp-servers/config.json

You can then point ollmcp at that file at startup with -j / --servers-json.

[!IMPORTANT] When using HTTP-based MCP servers, use the streamable_http type (not just http). Also check the Common MCP endpoint paths section below for typical endpoints.

Here a minimal working example let's say this is your ~/.config/ollmcp/mcp-servers/config.json:

{
  "mcpServers": {
    "github": {
      "type": "streamable_http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer mytoken"
      }
    }
  }
}

[!TIP] When using GitHub MCP server, make sure to replace "mytoken" with your actual GitHub API token.

With that file in place you can connect using:

ollmcp -j ~/.config/ollmcp/mcp-servers/config.json

Here you can find a GitHub issue related to this common pitfall: https://github.com/jonigl/mcp-client-for-ollama/issues/112#issuecomment-3446569030

Demo

A short demo (asciicast) that should help anyone reproduce the working setup quickly. This example uses an MCP server example with streamable HTTP protocol usage:

Common MCP endpoint paths

Streamable HTTP MCP servers typically expose the MCP endpoint at /mcp (e.g., https://host/mcp), while SSE servers commonly use /sse (e.g., https://host/sse). Below is an excerpt from the MCP specification (2025-06-18): > The server MUST provide a single HTTP endpoint path (hereafter referred to as the MCP endpoint) that supports both POST and GET methods. For example, this could be a URL like https://example.com/mcp.

You can find more details in the MCP specification version 2025-06-18 - Transports.

Advanced Model Configuration

The model-config (mc) command opens the advanced model settings interface, allowing you to fine-tune how the model generates responses:

System Prompt

• System Prompt: Set the model's role and behavior to guide responses.

Key Parameters

• System Prompt: Set the model's role and behavior to guide responses.
• Context Window (num_ctx): Set how much chat history the model uses. Balance with memory usage and performance.
• Keep Tokens: Prevent important tokens from being dropped
• Max Tokens: Limit response length (0 = auto)
• Seed: Make outputs reproducible (set to -1 for random)
• Temperature: Control randomness (0 = deterministic, higher = creative)
• Top K / Top P / Min P / Typical P: Sampling controls for diversity
• Repeat Last N / Repeat Penalty: Reduce repetition
• Presence/Frequency Penalty: Encourage new topics, reduce repeats
• Stop Sequences: Custom stopping points (up to 8)
• Batch Size (num_batch): Controls internal batching of requests; larger values can increase throughput but use more memory.

Commands

• Enter parameter numbers 1-15 to edit settings
• Enter sp to edit the system prompt
• Use u1, u2, etc. to unset parameters, or uall to reset all
• h/help: Show parameter details and tips
• undo: Revert changes
• s/save: Apply changes
• q/quit: Cancel

Example Configurations

• Factual: temperature: 0.0-0.3, top_p: 0.1-0.5, seed: 42
• Creative: temperature: 1.0+, top_p: 0.95, presence_penalty: 0.2
• Reduce Repeats: repeat_penalty: 1.1-1.3, presence_penalty: 0.2, frequency_penalty: 0.3
• Balanced: temperature: 0.7, top_p: 0.9, typical_p: 0.7
• Reproducible: seed: 42, temperature: 0.0
• Large Context: num_ctx: 8192 or higher for complex conversations requiring more context

[!TIP] All parameters default to unset, letting Ollama use its own optimized values. Use help in the config menu for details and recommendations. Changes are saved with your configuration.

Human-in-the-Loop (HIL) Configuration

• Default State: HIL confirmations are enabled by default for safety
• Toggle Command: Use /human-in-the-loop or /hil to toggle on/off
• Persistent Settings: HIL preference is saved with your configuration
• Quick Disable: Choose "disable" during any confirmation to turn off permanently
• Session Auto-Approve: Use "session" during confirmation to approve all tools for current query
• Query Abort: Use "abort" during confirmation to immediately stop the query without saving
• Re-enable: Use the hil command anytime to turn confirmations back on

Benefits: - Enhanced Safety: Prevent accidental or unwanted tool executions - Awareness: Understand what actions the model is attempting to perform - Selective Control: Choose which operations to allow on a case-by-case basis - Flexible Workflow: Session mode for efficient multi-tool queries, individual approval for sensitive operations - Clean Abort: Stop problematic queries immediately without polluting conversation history - Peace of Mind: Full visibility and control over automated actions

Configuration Management

[!TIP] It will automatically load the default configuration from ~/.config/ollmcp/config.json if it exists.

The client supports saving and loading tool configurations between sessions:

• When using save-config, you can provide a name for the configuration or use the default
• Configurations are stored in ~/.config/ollmcp/ directory
• The default configuration is saved as ~/.config/ollmcp/config.json
• Named configurations are saved as ~/.config/ollmcp/{name}.json

The configuration saves:

• Current model selection
• Advanced model parameters (system prompt, temperature, sampling settings, etc.)
• Enabled/disabled status of all tools
• Context retention settings
• Thinking mode settings
• Answer display mode preference
• Tool execution display preferences
• Performance metrics display preferences
• Human-in-the-Loop confirmation settings

Server Configuration Format

The JSON configuration file supports STDIO, SSE, and Streamable HTTP server types (MCP 1.10.1):

{
  "mcpServers": {
    "stdio-server": {
      "command": "command-to-run",
      "args": ["arg1", "arg2", "..."],
      "env": {
        "ENV_VAR1": "value1",
        "ENV_VAR2": "value2"
      },
      "disabled": false
    },
    "sse-server": {
      "type": "sse",
      "url": "http://localhost:8000/sse",
      "headers": {
        "Authorization": "Bearer your-token-here"
      },
      "disabled": true
    },
    "http-server": {
      "type": "streamable_http",
      "url": "http://localhost:8000/mcp",
      "headers": {
        "X-API-Key": "your-api-key-here"
      },
      "disabled": false
    }
  }
}