MCP Server: Ollama Deep Researcher

Core Functionality

Research Process

1. Generate a web search query

2. Gather web search results via [Tavily](https://www.tavily.com/) or [Perplexity API](https://www.perplexity.ai/hub/faq/pplx-api)

3. Summarize the search results

4. Reflect on the summary to examine knowledge gaps

5. Generate new search queries to address the gaps

6. Iteratively improve the summary through multiple research cycles

7. Provide a final markdown summary with all sources used

Prerequisites

• Node.js (for running the MCP server) - Download and install from https://nodejs.org/ - Ensure Node.js is added to your system PATH

• Python 3.10 or higher

• Compute (CPU/GPU) capable of running your selected Ollama model

• At least 8GB of RAM for running larger language models

• Required API keys: - Tavily API key (get one at https://tavily.com) - Perplexity API key (get one at https://perplexity.ai) - LangSmith API key (get one at https://smith.langchain.com) for tracing and monitoring

1. Restart your terminal/computer after installation

2. Add Node.js to your system PATH: - Windows: Edit system environment variables Environment Variables Path Add Node.js installation directory - macOS/Linux: Usually handled by the installer

Installation

Option 1: Standard Installation

1. Download and install [Ollama](https://ollama.com/download) for your platform

2. Clone this repository and install dependencies:

1. Install Python dependencies:

1. Build the TypeScript code:

1. Pull a local LLM from [Ollama](https://ollama.com/search):

Option 2: Docker Installation

1. Download and install [Docker](https://www.docker.com/products/docker-desktop/) for your platform

2. Clone this repository:

1. Create a `.env` file with your API keys (you can copy from `.env.example`):

1. Make the helper script executable:

1. Build and run the Docker container:

1. Ensure Ollama is running on your host machine:

• `./run-docker.sh start` - Build and start the Docker container

• `./run-docker.sh stop` - Stop the Docker container

• `./run-docker.sh restart` - Restart the Docker container

• `./run-docker.sh logs` - Show logs from the Docker container

• `./run-docker.sh status` - Check the status of the Docker container

• `./run-docker.sh help` - Show help message

• `run-docker.bat start` - Build and start the Docker container

• `run-docker.bat stop` - Stop the Docker container

• `run-docker.bat restart` - Restart the Docker container

• `run-docker.bat logs` - Show logs from the Docker container

• `run-docker.bat status` - Check the status of the Docker container

• `run-docker.bat help` - Show help message

Client Configuration

• macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

• Windows: `%APPDATA%\Claude\claude_desktop_config.json`

• Windows: `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`

• macOS: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`

• Linux: `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`

Option 1: Standard Installation Configuration

• Windows: Use `C:\\Users\\username\\path\\to\\mcp-server-ollama-deep-researcher`

• macOS/Linux: Use `/Users/username/path/to/mcp-server-ollama-deep-researcher`

Option 2: Docker Installation Configuration

Tracing and Monitoring

1. **Operation Tracing**: - All LLM interactions are traced - Web search operations are monitored - Research workflow steps are tracked

2. **Performance Monitoring**: - Response times for each operation - Success/failure rates - Resource utilization

3. **Debugging and Optimization**: - Detailed traces for troubleshooting - Performance bottleneck identification - Query optimization insights

MCP Resources

1. **Persistent Access** - Results accessible via `research://{topic}` URIs - Automatic storage of completed research - JSON-formatted content with metadata

2. **Resource Panel Integration** - Research appears in MCP client's resource panel - Easy access to past research topics - Timestamp and description for each result

3. **Context Management** - Efficient reuse of research in conversations - Reduced token usage through resource references - Selective inclusion of research context

Available Tools

Configure

• **maxLoops**: Number of research iterations (1-5)

• **llmModel**: Ollama model to use (e.g., "deepseek-r1:1.5b", "llama3.2")

• **searchApi**: Search API to use ("perplexity" or "tavily")

Research

Get status

Prompting

Using the Default Search API, Model, and Max Iterations (loops)

Change Default Config and Start Research

The Ollama Research Workflow

1. Given a user-provided topic, use a local LLM (via [Ollama](https://ollama.com/search)) to generate a web search query

2. Uses a search engine (configured for [Tavily](https://www.tavily.com/)) to find relevant sources

3. Uses LLM to summarize the findings from web search related to the user-provided research topic

4. Then, it uses the LLM to reflect on the summary, identifying knowledge gaps

5. It generates a new search query to address the knowledge gaps

6. The process repeats, with the summary being iteratively updated with new information from web search

7. It will repeat down the research rabbit hole

8. Runs for a configurable number of iterations

Outputs

System Integration Overview

Troubleshooting

Ollama Connection Issues

• Make sure Ollama is running: Execute `ollama list` in your terminal

• Try running ollama in terminal mode by closing the app (System Tray/Menu Bar), and executing `ollama serve`

• Check if Ollama is accessible at `localhost:11434`, `0.0.0.0:11434`, or `127.0.0.1:11434`

API Key Issues

• Verify your API key is correctly set in the configuration file

• Verify your path arg points to the actual location of the index.js in this repo

• Ensure there are no extra spaces or quotes around the API key

• Check if your API key has sufficient credits/permissions

MCP Server Issues

• Use the MCP Inspector for debugging:

Docker Issues

• If you're having issues with the Docker container: - Check if the container is running: `docker ps` - View container logs: `docker logs ollama-deep-researcher-mcp` - Ensure your `.env` file contains valid API keys - Verify Ollama is running on your host machine and accessible from the container - If using host.docker.internal doesn't work, try using your host machine's IP address in the OLLAMA_BASE_URL environment variable - For network issues between containers, ensure they're on the same Docker network

• If you're running Ollama in a container: - Uncomment the Ollama service in docker-compose.yml - Ensure the Ollama container has enough resources allocated - Pull the model in the Ollama container: `docker exec -it ollama ollama pull deepseek-r1:8b`

Build Issues

• If `npm run build` fails with "'node' is not recognized": 1. Ensure Node.js is properly installed 2. Add Node.js to your system PATH: - Windows: Edit system environment variables Environment Variables Path Add Node.js installation directory - macOS/Linux: Usually handled by the installer 3. Restart your terminal/computer 4. Try running `node --version` to verify the installation

Python Issues

• Ensure Python is in your PATH

• Try using `python` instead of `python3`

• Check if pip is installed: `python -m pip --version`

• Use `python3` instead of `python`

• Check if pip is installed: `python3 -m pip --version`

• You may need to install pip: `sudo apt install python3-pip` (Ubuntu/Debian) or `brew install python3` (macOS)

Error Handling

• Missing or invalid API keys

• Configuration issues

• Search API problems

• LLM processing errors

Enhancements Needed

• Tighter re-integration and validation of langgraph for additional interesting use cases.

Architecture

Glama.ai Badge

Example Prompt and Output Transcript

Prompt

Configuration Output

Ollama Researcher Output

Claude Final Output