Installation - OpenGround

Overview

The OpenGround MCP server provides official documentation search capabilities to AI agents through the Model Context Protocol (MCP). This guide covers installation for different AI agents and development environments.

Prerequisites

Python 3.11+

OpenGround requires Python 3.11 or higher.

python --version  # Should be 3.11 or higher

Install OpenGround

Install the OpenGround package from PyPI:

pip install openground

Or with pipx for isolated installation:

pipx install openground

Add documentation libraries

Add at least one documentation library to make the MCP server useful:

# Add a library (this will download and index documentation)
openground add fastapi --version latest

# Verify installation
openground list

Installation by Agent

Claude Desktop

Locate configuration file

Find your Claude Desktop configuration file:macOS:

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

Windows:

%APPDATA%/Claude/claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

Add OpenGround MCP server

Edit the configuration file to add the OpenGround server:

{
  "mcpServers": {
    "openground": {
      "command": "python",
      "args": ["-m", "openground.server"]
    }
  }
}

If using pipx:

{
  "mcpServers": {
    "openground": {
      "command": "pipx",
      "args": ["run", "openground", "serve"]
    }
  }
}

Restart Claude Desktop

Completely quit and restart Claude Desktop for changes to take effect.

Verify installation

In Claude Desktop, you should see the OpenGround tools available:

search_documents_tool
list_libraries_tool
get_full_content_tool

Test by asking: “What libraries are available in OpenGround?”

Continue.dev

Open Continue configuration

Open the Continue configuration file:

~/.continue/config.json

Add MCP server

Add OpenGround to the mcpServers section:

{
  "mcpServers": [
    {
      "name": "openground",
      "command": "python",
      "args": ["-m", "openground.server"],
      "transport": "stdio"
    }
  ]
}

Restart Continue

Restart your IDE or reload the Continue extension.

Cline (VSCode)

Open Cline settings

In VSCode:

Open Command Palette (Cmd/Ctrl + Shift + P)
Search for “Cline: Open Settings”

Configure MCP server

In the MCP Servers section, add:

{
  "openground": {
    "command": "python",
    "args": ["-m", "openground.server"]
  }
}

Restart Cline

Reload VSCode or restart the Cline extension.

Zed Editor

Open Zed settings

Open Zed settings file:macOS/Linux:

~/.config/zed/settings.json

Add MCP server configuration

{
  "context_servers": {
    "openground": {
      "command": "python",
      "args": ["-m", "openground.server"]
    }
  }
}

Restart Zed

Restart Zed editor to load the new MCP server.

Custom MCP Client

For custom integrations using the MCP SDK:

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

server_params = StdioServerParameters(
    command="python",
    args=["-m", "openground.server"],
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        
        # List available tools
        tools = await session.list_tools()
        print(tools)
        
        # Call a tool
        result = await session.call_tool(
            "list_libraries_tool",
            arguments={}
        )
        print(result)

Virtual Environment Setup

If you need to use a specific Python virtual environment:

Option 1: Activate in command

{
  "mcpServers": {
    "openground": {
      "command": "/path/to/venv/bin/python",
      "args": ["-m", "openground.server"]
    }
  }
}

Option 2: Use shell wrapper

Create a shell script ~/.local/bin/openground-mcp.sh:

#!/bin/bash
source /path/to/venv/bin/activate
python -m openground.server

Make it executable:

chmod +x ~/.local/bin/openground-mcp.sh

Configure MCP client:

{
  "mcpServers": {
    "openground": {
      "command": "/Users/yourname/.local/bin/openground-mcp.sh",
      "args": []
    }
  }
}

Verifying Installation

Check Server Startup

Run the server manually to verify it starts without errors:

python -m openground.server

You should see:

[info] Background initialization started...
[info] Background initialization complete (took 1.23s). Server is fully ready.

Test Tools

In your MCP client, test each tool:

1. List libraries:
   "What documentation libraries are available?"
   
2. Search:
   "Search FastAPI docs for authentication examples"
   
3. Get full content:
   "Show me the full page for [URL from search result]"

Common Installation Issues

Python Not Found

Error: command not found: python Solution: Use full path to Python or specify python3:

{
  "command": "python3",
  "args": ["-m", "openground.server"]
}

Module Not Found

Error: No module named 'openground' Solution: Install openground in the correct Python environment:

# Find which Python is used
which python

# Install openground for that Python
python -m pip install openground

Server Times Out

Error: MCP server fails to initialize or times out Cause: Background initialization might be taking too long on first run Solution:

Pre-warm the server by running it manually once:

python -m openground.server
# Wait for "fully ready" message, then Ctrl+C

Ensure you have at least one library added:
```
openground list
```

Permission Denied

Error: Permission errors when accessing database Solution: Check permissions on OpenGround data directory:

# Linux/macOS
ls -la ~/.local/share/openground/
chmod -R u+rw ~/.local/share/openground/

# Windows
# Verify AppData/Local/openground permissions

Empty Library List

Symptom: list_libraries_tool returns {} Solution: Add libraries first:

openground add fastapi
openground add django --version 5.0
openground list  # Verify they're added

Updating OpenGround

To update to the latest version:

pip install --upgrade openground

Or with pipx:

pipx upgrade openground

After updating, restart your MCP client to load the new version.

Uninstallation

Remove MCP Server

Remove the openground entry from your MCP client configuration
Restart the MCP client

Uninstall Package

pip uninstall openground

Or with pipx:

pipx uninstall openground

Remove Data

To completely remove all OpenGround data:

# Linux/macOS
rm -rf ~/.local/share/openground
rm -rf ~/.config/openground
rm -rf ~/.openground

# Windows
# Delete these folders:
# %LOCALAPPDATA%\openground
# %USERPROFILE%\.openground

Next Steps

Configuration

Configure OpenGround settings, environment variables, and optimize performance

Search Documents

Learn how to use the search_documents_tool effectively

List Libraries

Explore available documentation libraries and versions

Tools

Setup

Documentation Index

​Overview

​Prerequisites

​Installation by Agent

​Claude Desktop

​Continue.dev

​Cline (VSCode)

​Zed Editor

​Custom MCP Client

​Virtual Environment Setup

​Option 1: Activate in command

​Option 2: Use shell wrapper

​Verifying Installation

​Check Server Startup

​Test Tools

​Common Installation Issues

​Python Not Found

​Module Not Found

​Server Times Out

​Permission Denied

​Empty Library List

​Updating OpenGround

​Uninstallation

​Remove MCP Server

​Uninstall Package

​Remove Data

​Next Steps