Skip to main content

​
OpenCode Integration

Integrate OpenGround with OpenCode to search documentation during your AI-assisted development sessions.

​
Prerequisites

1

Install OpenGround

pip install openground
2

Add Documentation

Index at least one library:
openground add fastapi --source https://github.com/tiangolo/fastapi.git --docs-path docs -y
3

Install OpenCode

Download from opencode.sh

​
Installation

OpenGround provides an automatic installer for OpenCode: 
openground install-mcp --opencode
This command:
  1. Locates your OpenCode config at ~/.config/opencode/opencode.json
  2. Creates a timestamped backup of existing config
  3. Safely merges the OpenGround MCP server configuration
  4. Validates JSON before writing
Success! You should see: “Successfully installed openground to OpenCode!”

​
Configuration Structure

The installer adds this configuration to opencode.json: 
{
  "mcp": {
    "openground": {
      "type": "local",
      "command": ["openground-mcp"],
      "enabled": true
    }
  }
}

​
Configuration File Location

OpenCode stores its configuration at: 
~/.config/opencode/opencode.json

​
Manual Installation

If you prefer to manually edit the configuration:
1

Generate Configuration

openground install-mcp
This displays the JSON without modifying files
2

Locate OpenCode Config

Navigate to ~/.config/opencode/opencode.json
3

Edit Configuration

Add the OpenGround server to the mcp section:
{
  "mcp": {
    "openground": {
      "type": "local",
      "command": ["openground-mcp"],
      "enabled": true
    }
  }
}
If you have existing MCP servers, add OpenGround alongside them:
{
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["some-other-server"],
      "enabled": true
    },
    "openground": {
      "type": "local",
      "command": ["openground-mcp"],
      "enabled": true
    }
  }
}
4

Validate JSON

Ensure proper syntax (no trailing commas, quotes, etc.)

​
Configuration Details

​
OpenCode MCP Schema

OpenCode’s MCP configuration differs slightly from other clients:
FieldValueDescription
type"local"Indicates a local subprocess server
command["openground-mcp"]Command as an array (not a string)
enabledtrueWhether the server is active

​
Command Resolution

The installer uses the full path to openground-mcp if found in PATH: 
{
  "mcp": {
    "openground": {
      "type": "local",
      "command": ["/usr/local/bin/openground-mcp"],
      "enabled": true
    }
  }
}

​
Transport Protocol

OpenGround uses stdio (standard input/output):
  • OpenCode spawns openground-mcp as a subprocess
  • Communication via stdin/stdout
  • No network ports required

​
Backup Files

The installer creates timestamped backups before making changes: 
~/.config/opencode/opencode.json.backup.20240228_153045
Restore from backup if needed: 
cp ~/.config/opencode/opencode.json.backup.YYYYMMDD_HHMMSS ~/.config/opencode/opencode.json

​
Verification

1

Restart OpenCode

Completely quit and restart OpenCode
2

Check MCP Status

In OpenCode settings or console, verify OpenGround MCP is connected
3

Test Tools

Ask OpenCode: “What documentation is available in openground?”OpenCode should call list_libraries_tool and display your indexed libraries

​
Using OpenGround in OpenCode

​
Automatic Tool Invocation

OpenCode will automatically use OpenGround when appropriate: 
You: How do I create a FastAPI route with path parameters?

OpenCode: Let me check the FastAPI documentation...
[Calls mcp__openground__search_documents_tool]

According to the official FastAPI docs:
...

​
Explicit Documentation Searches

Request specific documentation searches: 
You: Search openground for React context API examples

OpenCode: [Searches React documentation]

​
Combining Code and Docs

OpenCode can analyze your code alongside documentation: 
You: Is this the correct way to use Django model validators?
[paste code]

OpenCode: [Analyzes code + searches Django docs for validator patterns]

​
Platform-Specific Configuration

​
macOS

No additional configuration needed. Works out of the box.

​
Linux

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

# Reload
source ~/.bashrc
Verify: 
which openground-mcp
# Should output: /home/username/.local/bin/openground-mcp

​
Windows

Add Python Scripts to PATH:
# Check availability
where openground-mcp
If not found:
  1. Open System Properties → Environment Variables
  2. Add to PATH: 
    C:\Users\YourUsername\AppData\Local\Programs\Python\Python311\Scripts
  3. Restart terminal/OpenCode
Run installer:
openground install-mcp --opencode

​
Advanced Configuration

​
Disable OpenGround Temporarily

Set enabled to false without removing the configuration: 
{
  "mcp": {
    "openground": {
      "type": "local",
      "command": ["openground-mcp"],
      "enabled": false
    }
  }
}

​
Use Specific Virtual Environment

Point to a specific Python environment: 
{
  "mcp": {
    "openground": {
      "type": "local",
      "command": ["/path/to/venv/bin/openground-mcp"],
      "enabled": true
    }
  }
}

​
Environment Variables

Pass custom environment variables: 
{
  "mcp": {
    "openground": {
      "type": "local",
      "command": ["openground-mcp"],
      "enabled": true,
      "env": {
        "OPENGROUND_CONFIG": "/custom/path/config.json"
      }
    }
  }
}

​
Multiple OpenGround Instances

Run separate instances with different databases: 
{
  "mcp": {
    "openground-work": {
      "type": "local",
      "command": ["/work/venv/bin/openground-mcp"],
      "enabled": true,
      "env": {
        "OPENGROUND_CONFIG": "~/.openground-work/config.json"
      }
    },
    "openground-oss": {
      "type": "local",
      "command": ["/oss/venv/bin/openground-mcp"],
      "enabled": true,
      "env": {
        "OPENGROUND_CONFIG": "~/.openground-oss/config.json"
      }
    }
  }
}

​
Troubleshooting

​
Configuration Not Applied

1

Verify File Location

Confirm opencode.json exists at ~/.config/opencode/
2

Check JSON Syntax

Validate with:
python -m json.tool ~/.config/opencode/opencode.json
3

Restart OpenCode Completely

Quit entirely (not just close window), then restart

​
Invalid JSON Error

If OpenCode reports JSON errors: 
# Restore from backup
cp ~/.config/opencode/opencode.json.backup.YYYYMMDD_HHMMSS ~/.config/opencode/opencode.json

# Re-run installer
openground install-mcp --opencode

​
Permission Denied

Fix file permissions: 
# Linux/macOS
chmod 644 ~/.config/opencode/opencode.json

# Windows: Right-click → Properties → Security → Edit

​
Command Not Found

1

Verify Installation

which openground-mcp  # macOS/Linux
where openground-mcp  # Windows
2

Use Full Path

Edit opencode.json with full path:
{
  "mcp": {
    "openground": {
      "type": "local",
      "command": ["/full/path/to/openground-mcp"],
      "enabled": true
    }
  }
}
3

Check PATH

Ensure Python bin/Scripts directory is in PATH

​
MCP Server Not Starting

Debug the server: 
# Test server manually
openground-mcp
# Should start without errors (Ctrl+C to exit)

# Check OpenCode logs for error messages

​
No Search Results

Verify documentation: 
# List libraries
openground list-libraries

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

​
Updating Configuration

Re-run the installer to update: 
openground install-mcp --opencode
The installer:
  1. Creates a new timestamped backup
  2. Preserves other MCP servers
  3. Updates only OpenGround configuration

​
Next Steps

Add Libraries

Index more documentation sources

Configure Search

Customize embedding models and retrieval

MCP Overview

Learn about MCP architecture

Custom Agents

Use with other MCP clients

Build docs developers (and LLMs) love

Get started for freeTalk to us