data-ai MCP Server
Harness the power of local LLMs with this TUI MCP Client for Ollama. Featuring all core MCP primitives (tools, prompts, resources), agent mode, multi-server, model switching, streaming responses, human-in-the-loop, thinking mode, model params config, system prompts, and saved preferences.
Discovered via github-topic:mcp and last synced 1d ago.
1. Install the package
pip install --upgrade ollmcp
Shortcut
Loads in
Current project only
Current project only
All your projects
Description
`a`
Provider's default effort (recommended for cloud)
> [!NOTE] > Local OpenAI-compatible servers (`ollama`, `llamacpp`, `llamafile`, `lmstudio`, `vllm`) typically run without an API key, point ollmcp at them with `--host`. Providers any-llm offers that are **not** OpenAI-compatible (e.g. `anthropic`, `gemini`, `mistral`, `groq`, `cohere`) are not supported yet. > [!WARNING] > **Capability detection limitation:** ollmcp only reads real per-model capabilities (`tools`, `vision`, `thinking`) from Ollama. For every non-Ollama provider, all three capabilities are currently assumed available and shown as such in the model list and badges, so a model may be reported as supporting tools, vision, or thinking even when it doesn't. If a model lacks a capability, the provider's API will return an error when you try to use it. #### API key resolution order For the selected provider, ollmcp resolves the API key in this order, from **highest** to **lowest** precedence: 1. The `--api-key` / `-k` flag. 2. The `$OLLMCP_API_KEY` environment variable (provider-agnostic, applies to whichever provider you selected with `--provider`). 3. The per-provider key saved in `~/.config/ollmcp/config.json` (present only if it was once passed via `--api-key`). 4. The provider's own native environment variable, detected by [any-llm](https://github.com/mozilla-ai/any-llm) (e.g. `OPENAI_API_KEY`, `OPENROUTER_API_KEY`). > [!WARNING] > A saved per-provider key (3) takes precedence over the provider's native environment variable (4). So if you previously saved a **wrong or expired** key, setting `OPENAI_API_KEY` (or the equivalent) alone will **not** override it. To fix it, either pass the correct key with `--api-key`, or remove the stale `apiKey` from that provider's profile in `~/.config/ollmcp/config.json`. ### Usage Examples Simplest way to run the client: ```bash ollmcp ``` > [!TIP] > This connects to all servers registered via `ollmcp mcp add` and uses the model from your saved configuration file, or the first available model in Ollama if none is saved. Pass `--claude-desktop` to also include servers from Claude Desktop's config. Connect to a single server: ```bash ollmcp --mcp-server /path/to/weather.py --model llama3.2:3b # Or using short flags: ollmcp -s /path/to/weather.py -m llama3.2:3b ``` Connect to multiple servers: ```bash ollmcp --mcp-server /path/to/weather.py --mcp-server /path/to/filesystem.js # Or using short flags: ollmcp -s /path/to/weather.py -s /path/to/filesystem.js ``` > [!TIP] > If `--model` is not specified, the model from your saved configuration file is used; otherwise the first available model in Ollama is selected automatically (you'll be told how to pull one if none are installed). Use a JSON configuration file: ```bash ollmcp --servers-json /path/to/servers.json --model llama3.2:1b # Or using short flags: ollmcp -j /path/to/servers.json -m llama3.2:1b ``` > [!TIP] > See the [Server Configuration Format](#server-configuration-format) section for details on how to structure the JSON file. Use a custom Ollama host: ```bash ollmcp --host http://localhost:22545 --servers-json /path/to/servers.json # Or using short flags: ollmcp -H http://localhost:22545 -j /path/to/servers.json ``` Use a different LLM provider (OpenAI or any OpenAI-compatible API): ```bash ollmcp --provider openai --api-key $OPENAI_API_KEY --model gpt-5.5 # OpenAI-compatible providers (e.g. OpenRouter, DeepSeek); override the endpoint with --host if needed: ollmcp --provider openrouter --api-key $OPENROUTER_API_KEY -m openrouter/free ``` > [!TIP] > Provider settings (model, host, API key) are remembered **per provider**. Once saved with `/save-config`, plain `ollmcp` resumes your last-used provider. See [Configuration Management](#configuration-management) for details. Connect to SSE or Streamable HTTP servers by URL: ```bash ollmcp --mcp-server-url http://localhost:8000/sse --model qwen2.5:latest # Or using short flags: ollmcp -u http://localhost:8000/sse -m qwen2.5:latest ``` Connect to multiple URL servers: ```bash ollmcp --mcp-server-url http://localhost:8000/sse --mcp-server-url http://localhost:9000/mcp # Or using short flags: ollmcp -u http://localhost:8000/sse -u http://localhost:9000/mcp ``` Mix local scripts and URL servers: ```bash ollmcp --mcp-server /path/to/weather.py --mcp-server-url http://localhost:8000/mcp --model qwen3:1.7b # Or using short flags: ollmcp -s /path/to/weather.py -u http://localhost:8000/mcp -m qwen3:1.7b ``` Include Claude Desktop servers alongside other sources: ```bash ollmcp --mcp-server /path/to/weather.py --mcp-server-url http://localhost:8000/mcp --claude-desktop # Or using short flags: ollmcp -s /path/to/weather.py -u http://localhost:8000/mcp --claude-desktop ``` ### How Tool Calls Work 1. The client sends your query to Ollama with a list of available tools 2. If Ollama decides to use a tool, the client: - Displays the tool execution with formatted arguments and syntax highlighting - Shows a Human-in-the-Loop confirmation prompt (if enabled) allowing you to review and approve the tool call - Extracts the tool name and arguments from the model response - Calls the appropriate MCP server with these arguments (only if approved or HIL is disabled) - Shows the tool response in a structured, easy-to-read format (including image and unsupported-media summaries) - If the tool returned images and the current model supports vision, attaches the images to the next LLM message; otherwise displays a warning - Sends the tool result back to Ollama - If in Agent Mode, repeats the process if the model requests more tool calls 3. Finally, the client: - Displays the model's final response incorporating the tool results ### Agent Mode Some models may request multiple tool calls in a single conversation. The client supports an **Agent Mode** that allows for iterative tool execution: - When the model requests a tool call, the client executes it and sends the result back to the model - This process repeats until the model provides a final answer or reaches the configured loop limit - You can set the maximum number of iterations using the `/loop-limit` (`/ll`) command - The default loop limit is `7` to prevent infinite loops #### When the loop limit is reached Instead of silently stopping, the client pauses and asks you how to proceed:
Description
Remove the cap and run until the model stops requesting tools
Light reasoning
Discard the turn entirely (nothing saved to history)
More thorough reasoning
Choose exactly how many more iterations to allow
Fastest, least reasoning
Ask the model to summarise what it gathered so far and produce a final answer — preserves all tool results collected before the limit
Balanced — **default**
Maximum reasoning effort