Claude Code Integration

Install OpenGround MCP server for Claude Code using the claude CLI

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

Automatic Installation (Recommended)

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