Ollama Deep Researcher MCP server

This MCP server provides advanced research capabilities through local language models via Ollama. It retrieves and synthesizes information from the web to create comprehensive reports on any topic.

Installation

Prerequisites

• Node.js
• Python 3.10 or higher
• Compute capable of running Ollama models
• API keys for:
  • Tavily (search API)
  • Perplexity (alternative search API)
  • LangSmith (for tracing and monitoring)

Standard Installation

1. Download and install Ollama for your platform

2. Clone the repository and install dependencies:

git clone https://github.com/Cam10001110101/mcp-server-ollama-deep-researcher
cd mcp-server-ollama-deep-researcher
npm install

3. Install Python dependencies:

# Install uv (recommended)
pip install uv

# Then install project dependencies
uv pip install .

# Alternative using standard pip
pip install .  # Windows
pip3 install .  # macOS/Linux

4. Build the TypeScript code:

npm run build

5. Pull a local LLM from Ollama:

ollama pull deepseek-r1:8b

Docker Installation

1. Install Docker

2. Clone the repository:

git clone https://github.com/Cam10001110101/mcp-server-ollama-deep-researcher
cd mcp-server-ollama-deep-researcher

3. Create a .env file with your API keys:

cp .env.example .env
# Edit the .env file

4. Make the helper script executable and run:

chmod +x run-docker.sh
./run-docker.sh start

5. Ensure Ollama is running on your host machine:

ollama pull deepseek-r1:8b
ollama serve

Client Configuration

Add the server to your MCP client configuration:

Standard Installation Configuration

{
  "mcpServers": {
    "ollama-deep-researcher": {
      "command": "node",
      "args": ["path/to/mcp-server-ollama-deep-researcher/build/index.js"],
      "env": {
        "LANGSMITH_TRACING": "true",
        "LANGSMITH_ENDPOINT": "https://api.smith.langchain.com",
        "LANGSMITH_API_KEY": "your-langsmith-key",
        "LANGSMITH_PROJECT": "ollama-deep-researcher-mcp-server",
        "TAVILY_API_KEY": "your-tavily-key",
        "PERPLEXITY_API_KEY": "your-perplexity-key",
        "PYTHONPATH": "path/to/mcp-server-ollama-deep-researcher/src"
      }
    }
  }
}

Docker Installation Configuration

{
  "mcpServers": {
    "ollama-deep-researcher": {
      "command": "docker",
      "args": ["exec", "-i", "ollama-deep-researcher-mcp", "node", "build/index.js"],
      "env": {}
    }
  }
}

Using the Research Tools

Configure

Configure research parameters:

{
  "name": "configure",
  "arguments": {
    "maxLoops": 3,
    "llmModel": "deepseek-r1:1.5b",
    "searchApi": "tavily"
  }
}

Parameters:

• 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

Research any topic:

{
  "name": "research",
  "arguments": {
    "topic": "Austin LangChain, aimug.org"
  }
}

Get Status

Check progress of ongoing research:

{
  "name": "get_status",
  "arguments": {
    "_dummy": "dummy"
  }
}

Simple Prompting Examples

Using default configuration:

research AI-First Applications

Changing configuration and starting research:

Configure with perplexity and deepseek-r1:8b then research AI-First Applications

Troubleshooting

Ollama Connection Issues

• Verify Ollama is running: ollama list
• Try ollama serve in terminal mode
• Check if Ollama is accessible at localhost:11434, 0.0.0.0:11434, or 127.0.0.1:11434

API Key Issues

• Verify API keys are correctly set in your configuration
• Ensure there are no extra spaces around the API keys
• Check if keys have sufficient credits/permissions

MCP Server Issues

Use the MCP Inspector for debugging:

npx @modelcontextprotocol/inspector node path/to/server/index.js --model llama3.2 --max-loops 3 --search-api tavily

Docker Issues

• Check container status: docker ps
• View logs: docker logs ollama-deep-researcher-mcp
• Verify Ollama is accessible from the container
• Try using your host machine's IP address if host.docker.internal doesn't work

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.