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)

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:

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 :

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:

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:

setting

environmental variables

Setting up Ollama

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

Quickstart

install

Claude Desktop Settings

MacOS

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

Windows

Path: %APPDATA%/Claude/claude_desktop_config.json

Usage Example

Task Decomposition

To break down a complex task into manageable subtasks:

Result evaluation

To evaluate the results against specific criteria:

Running the Ollama model

To query an Ollama model directly:

development

Project Setup

1. Clone the repository:

2. Create and activate the virtual environment:

3. Install development dependencies:

Local Development

The project includes some useful development scripts:

Running the Server

option:

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

Running the tests

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:

2. Build the package distribution:

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

3. Publish to PyPI:

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:

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