Skip to main content

​
Claude Code Integration

Install OpenGround’s MCP server in Claude Code to enable real-time documentation search during conversations.

​
Prerequisites

1

Install OpenGround

pip install openground
2

Install Claude Code CLI

Follow the Claude Code CLI installation guide
3

Add Documentation

Index at least one library:
openground add react --source https://github.com/facebook/react.git --docs-path docs -y

​
Installation

OpenGround provides an automatic installer that uses the claude CLI: 
openground install-mcp --claude-code
This command:
  1. Removes any existing OpenGround MCP configuration
  2. Registers the openground-mcp server with Claude Code
  3. Configures stdio transport at user scope
Success! You should see: “Successfully installed openground to Claude Code!”

​
Manual Installation

If the automatic installer fails, you can manually install using the claude CLI: 
claude mcp add --transport stdio --scope user openground -- openground-mcp

​
Configuration Details

The automatic installer creates this configuration: 
{
  "mcpServers": {
    "openground": {
      "command": "openground-mcp"
    }
  }
}

​
Configuration Location

Claude Code stores MCP configurations at:
  • macOS: ~/.claude/mcp.json
  • Linux: ~/.config/claude/mcp.json
  • Windows: %APPDATA%\Claude\mcp.json

​
Transport Protocol

OpenGround uses stdio (standard input/output) transport:
  • Claude Code spawns openground-mcp as a subprocess
  • Communication happens over stdin/stdout
  • No network configuration required

​
Verification

1

Restart Claude Code

Quit and restart Claude Code completely
2

Check MCP Status

claude mcp list
You should see openground in the list
3

Test in Conversation

Ask Claude: “What libraries are available in openground?”Claude should call the list_libraries_tool and show your indexed documentation

​
Using OpenGround with Claude Code

​
Basic Usage

Once installed, Claude Code will automatically use OpenGround when appropriate: 
You: How do I use React hooks?

Claude: Let me search the official React documentation...
[Calls search_documents_tool]

Here's what I found in the React documentation:
...

​
Explicit Tool Usage

You can explicitly request documentation searches: 
You: Search openground for FastAPI dependency injection

Claude: [Calls list_libraries_tool, then search_documents_tool]

​
Claude Code Agent (Advanced)

For isolated documentation searches, you can create a dedicated OpenGround agent.

​
What is a Claude Code Agent?

Agents in Claude Code are subagents that:
  • Run in isolated contexts
  • Have access to specific tools
  • Can be invoked automatically or manually
  • Keep your main conversation focused

​
Installing the Agent

1

Create Agent Directory

mkdir -p ~/.claude/agents
2

Create Agent Definition

Create ~/.claude/agents/openground-docs-search.md:
---
name: openground-docs-search
description: Search official framework and library documentation from openground's local vector database.
tools: mcp__openground__list_libraries_tool, mcp__openground__search_documents_tool, mcp__openground__get_full_content_tool
model: sonnet
---

You are a documentation search specialist. Your job is to:

1. First, call list_libraries_tool to see what documentation is available
2. Search the documentation using search_documents_tool
3. Present focused results with source URLs
4. Use get_full_content_tool if more context is needed

Always confirm the library and version exist before searching.
Present results clearly with proper markdown formatting.
3

Restart Claude Code

Quit and restart for the agent to be recognized

​
Using the Agent

The agent runs in an isolated context to avoid cluttering your main conversation: Automatic invocation: 
You: How do I use React useEffect?

Claude: [Automatically invokes openground-docs-search agent]
Manual invocation: 
You: Use the openground-docs-search agent to find Django model examples

Claude: [Invokes agent explicitly]

​
Agent Workflow

1

List Available Libraries

Agent checks what documentation is in your database
2

Search Documentation

Performs semantic search for your query
3

Present Results

Shows relevant snippets with source URLs
4

Fetch Full Content

Gets complete pages when needed

​
Platform-Specific Notes

​
macOS

No special configuration needed. The openground-mcp command should be in your PATH after pip installation.

​
Linux

Ensure pip’s bin directory is in your PATH: 
# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

​
Windows

Ensure Python Scripts directory is in your PATH: 
# Check if openground-mcp is available
where openground-mcp
If not found, add Python Scripts to PATH: 
C:\Users\YourUsername\AppData\Local\Programs\Python\Python311\Scripts

​
WSL (Windows Subsystem for Linux)

If running Claude Code on Windows but OpenGround in WSL, use the WSL configuration: 
openground install-mcp --wsl
This generates a configuration using wsl.exe wrapper: 
{
  "mcpServers": {
    "openground": {
      "command": "wsl.exe",
      "args": ["openground-mcp"]
    }
  }
}

​
Troubleshooting

​
Error: ‘claude’ CLI not found

The claude CLI is not installed. Install it from: https://code.claude.com/docs/en/cli Alternatively, use manual configuration: 
openground install-mcp
# Copy the generated JSON to your Claude Code config

​
MCP Server Not Starting

1

Verify Installation

which openground-mcp
Should return the path to the executable
2

Test Server Manually

openground-mcp
Should start without errors (use Ctrl+C to exit)
3

Check Claude Code Logs

Look for error messages in Claude Code’s console or logs

​
No Search Results

Verify documentation is indexed: 
# List available libraries
openground list-libraries

# Add documentation if needed
openground add react --source https://github.com/facebook/react.git --docs-path docs -y

​
Agent Not Found

Make sure the agent file is in the correct location:
  • Global: ~/.claude/agents/openground-docs-search.md
  • Project: .claude/agents/openground-docs-search.md

​
Updating Configuration

To update your OpenGround MCP configuration: 
# Re-run the installer
openground install-mcp --claude-code
The installer automatically removes old configurations before installing.

​
Next Steps

Add Libraries

Index more documentation sources

Configure Search

Customize search behavior

MCP Overview

Learn more about MCP architecture

Custom Agents

Use with other MCP clients