ollama-MCP-server

A Model Context Protocol (MCP) server that communicates with Ollama

overview

This MCP server enables seamless integration between local Ollama LLM instances and MCP compatible applications, providing advanced task decomposition, evaluation and workflow management.

Key features:

• Task decomposition of complex problems

• Evaluation and validation of results

• Managing and running Ollama models

• Standardized communication via the MCP protocol

• Advanced error handling and detailed error messages

• Performance optimization (connection pooling, LRU cache)

Related MCP server: mcplex

component

resource

The server implements the following resources:

• task:// - the URI scheme for accessing individual tasks

• result:// - the URI scheme for accessing the evaluation result

• model:// - the URI scheme for accessing available Ollama models.

Each resource has the appropriate metadata and MIME type configured for optimal LLM interaction.

Prompt and tool relationships

In an MCP server, prompts and tools are closely related but have different roles.

• Prompts : Schema-like functions that provide a specific way of thinking and structure to the LLM

• Tool : Acts like a handler that actually executes the action

Each tool requires a corresponding schema (prompt) to effectively align the thinking skills of the LLM with the actual system functions.

prompt

The server provides some special prompts:

• decompose-task - Decompose a complex task into manageable subtasks

  • Get the task description and optional parameters at a granular level

  • Returns a structured breakdown of dependencies and estimated complexity

• evaluate-result - Analyzes task results against specified criteria

  • Obtain results and evaluation parameters

  • Returns a detailed evaluation with a score and suggestions for improvement

tool

The server implements several powerful tools:

• add-task

  • Required parameters: name (string), description (string)

  • Optional parameters: priority (number), deadline (string), tags (array)

  • Creates a new task in the system and returns its identifier.

  • Corresponding Schema: Data Validation Schema for Task Creation

• decompose-task

  • Required parameters: task_id (string), granularity (string: "high"|"medium"|"low")

  • Optional parameter: max_subtasks (number)

  • Use Ollama to break down complex tasks into manageable subtasks

  • Corresponding schema: decompose-task prompt above

• evaluate-result

  • Required parameters: result_id (string), criteria (object)

  • Optional parameter: detailed (Boolean)

  • Evaluate results against specified criteria and provide feedback

  • Corresponding schema: evaluate-result prompt above

• run-model

  • Required parameters: model (string), prompt (string)

  • Optional parameters: temperature (number), max_tokens (number)

  • Runs the Ollama model with the specified parameters.

  • Corresponding schema: Ollama model execution parameters validation schema

New features and improvements

Extended Error Handling

The server provides more detailed and structured error messages, allowing the client application to handle the error more effectively. Example error response:

{
  "error": {
    "message": "Task not found: task-123",
    "status_code": 404,
    "details": {
      "provided_id": "task-123"
    }
  }
}

Performance Optimization

• Connection Pooling : Using a shared HTTP connection pool improves request performance and reduces resource utilization.

• LRU Cache : Caching responses to identical or similar requests improves response time and reduces the load on the Ollama servers.

These settings can be adjusted in config.py :

# パフォーマンス関連設定
cache_size: int = 100                 # キャッシュに保存する最大エントリ数
max_connections: int = 10             # 同時接続の最大数
max_connections_per_host: int = 10    # ホストごとの最大接続数
request_timeout: int = 60             # リクエストタイムアウト（秒）

Model specification function

overview

The Ollama-MCP-Server provides the flexibility to specify Ollama models in multiple ways.

Model specification precedence

Models are specified in the following order of priority:

1. Parameters when calling the tool ( model parameters)

2. MCP config file env section

3. Environment variable ( OLLAMA_DEFAULT_MODEL )

4. Default value ( llama3 )

Model specification using MCP configuration files

For use with clients such as Claude Desktop, you can specify the model using the MCP configuration file:

{
  "mcpServers": {
    "ollama-MCP-server": {
      "command": "python",
      "args": [
        "-m",
        "ollama_mcp_server"
      ],
      "env": [
        {"model": "llama3:latest"}
      ]
    }
  }
}

Check available models

At server startup, the server checks whether the configured model exists. If the model is not found, a warning is logged. Also, the run-model tool returns a list of available models, allowing the user to select a valid model.

Improved error handling

If the specified model does not exist or a communication error occurs, a detailed error message is provided, including a list of available models, allowing users to quickly resolve the issue.

test

The project includes a comprehensive test suite:

• Unit testing : testing the functionality of individual components

• Integration testing : Testing the end-to-end workflow

To run the test:

# すべてのテストを実行
python -m unittest discover

# 特定のテストを実行
python -m unittest tests.test_integration

setting

environmental variables

OLLAMA_HOST=http://localhost:11434
DEFAULT_MODEL=llama3
LOG_LEVEL=info

Setting up Ollama

Make sure Ollama is installed and running on the appropriate model:

# Ollamaをインストール（まだインストールされていない場合）
curl -fsSL https://ollama.com/install.sh | sh

# 推奨モデルをダウンロード
ollama pull llama3
ollama pull mistral
ollama pull qwen2

Quickstart

install

pip install ollama-mcp-server

Claude Desktop Settings

MacOS

Path: ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows

Path: %APPDATA%/Claude/claude_desktop_config.json

"mcpServers": {
  "ollama-MCP-server": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/ollama-MCP-server",
      "run",
      "ollama-MCP-server"
    ],
    "ENV":["model":"deepseek:r14B"]
  }
}

"mcpServers": {
  "ollama-MCP-server": {
    "command": "uvx",
    "args": [
      "ollama-MCP-server"
    ]
  }
}

Usage Example

Task Decomposition

To break down a complex task into manageable subtasks:

result = await mcp.use_mcp_tool({
    "server_name": "ollama-MCP-server",
    "tool_name": "decompose-task",
    "arguments": {
        "task_id": "task://123",
        "granularity": "medium",
        "max_subtasks": 5
    }
})

Result evaluation

To evaluate the results against specific criteria:

evaluation = await mcp.use_mcp_tool({
    "server_name": "ollama-MCP-server",
    "tool_name": "evaluate-result",
    "arguments": {
        "result_id": "result://456",
        "criteria": {
            "accuracy": 0.4,
            "completeness": 0.3,
            "clarity": 0.3
        },
        "detailed": true
    }
})

Running the Ollama model

To query an Ollama model directly:

response = await mcp.use_mcp_tool({
    "server_name": "ollama-MCP-server",
    "tool_name": "run-model",
    "arguments": {
        "model": "llama3",
        "prompt": "量子コンピューティングを簡単な言葉で説明してください",
        "temperature": 0.7
    }
})

development

Project Setup

1. Clone the repository:

git clone https://github.com/yourusername/ollama-MCP-server.git
cd ollama-MCP-server

2. Create and activate the virtual environment:

python -m venv venv
source venv/bin/activate  # Windowsの場合: venv\Scripts\activate

3. Install development dependencies:

uv sync --dev --all-extras

Local Development

The project includes some useful development scripts:

Running the Server

./run_server.sh

option:

• --debug : Run in debug mode (log level: DEBUG)

• --log=LEVEL : Specify the log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)

Running the tests

./run_tests.sh

option:

• --unit : Run only unit tests

• --integration : Run only integration tests

• --all : run all tests (default)

• --verbose : Detailed test output

Build and publish

To prepare a package for distribution:

1. Sync dependencies and update lock files:

uv sync

2. Build the package distribution:

uv build

This will create a source and wheels distribution in dist/ directory.

3. Publish to PyPI:

uv publish

Note: You must configure your PyPI credentials in an environment variable or command flag:

• Token: --token or UV_PUBLISH_TOKEN

• Or username/password: --username / UV_PUBLISH_USERNAME and --password / UV_PUBLISH_PASSWORD

debug

Debugging MCP servers can be difficult because they run over stdio, for the best debugging experience we highly recommend using MCP Inspector .

To start MCP Inspector using npm , run the following command:

npx @modelcontextprotocol/inspector uv --directory /path/to/ollama-MCP-server run ollama-mcp-server

On launch, the Inspector will show you a URL that you can visit in your browser to start debugging.

Architect

contribution

Contributions are welcome! Feel free to submit a pull request.

1. Fork the repository

2. Create a feature branch ( git checkout -b feature/amazing-feature )

3. Commit the changes ( git commit -m 'Add some amazing feature' )

4. Push to the branch ( git push origin feature/amazing-feature )

5. Opening a pull request

license

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgements

• The Model Context Protocol team for providing excellent protocol design

• The Ollama project makes local LLM runs accessible

• All contributors to this project