Skip to main content

​
Cursor Integration

Integrate OpenGround with Cursor to search documentation directly within your IDE conversations.

​
Prerequisites

1

Install OpenGround

pip install openground
2

Add Documentation

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

Install Cursor

Download from cursor.sh

​
Installation

OpenGround provides an automatic installer that safely modifies Cursor’s MCP configuration: 
openground install-mcp --cursor
This command:
  1. Locates your Cursor config directory
  2. Creates a backup of existing mcp.json (if it exists)
  3. Safely merges the OpenGround server configuration
  4. Validates the JSON before writing
Success! You should see: “Successfully installed openground to Cursor!”

​
What Gets Configured

The installer adds this configuration to your mcp.json: 
{
  "mcpServers": {
    "openground": {
      "command": "openground-mcp"
    }
  }
}
If you already have other MCP servers configured, they will be preserved.

​
Configuration File Locations

Cursor’s MCP configuration is stored at platform-specific locations: 
~/.cursor/mcp.json

​
Manual Installation

If you prefer to edit the configuration manually:
1

Generate Configuration

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

Locate Cursor Config

Navigate to your platform’s config directory (see locations above)
3

Edit mcp.json

Create or edit the mcp.json file:
{
  "mcpServers": {
    "openground": {
      "command": "openground-mcp"
    }
  }
}
If you have existing servers, add openground to the mcpServers object:
{
  "mcpServers": {
    "existing-server": {
      "command": "some-other-command"
    },
    "openground": {
      "command": "openground-mcp"
    }
  }
}
4

Validate JSON

Ensure your JSON is valid (no trailing commas, proper quotes)

​
Configuration Details

​
Command Resolution

The installer automatically resolves the full path to openground-mcp: 
{
  "mcpServers": {
    "openground": {
      "command": "/usr/local/bin/openground-mcp"
    }
  }
}
If the command is not in your PATH, the full path will be used automatically.

​
Transport Protocol

OpenGround uses stdio transport:
  • Cursor spawns openground-mcp as a subprocess
  • Communication via stdin/stdout
  • No network ports or authentication needed

​
Backup Files

The automatic installer creates timestamped backups: 
~/.cursor/mcp.json.backup.20240228_143022
You can restore from a backup if needed: 
cp ~/.cursor/mcp.json.backup.YYYYMMDD_HHMMSS ~/.cursor/mcp.json

​
Verification

1

Restart Cursor

Completely quit and restart Cursor
2

Open Cursor Chat

Start a new chat conversation
3

Test OpenGround Tools

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

​
Using OpenGround in Cursor

​
Automatic Usage

Cursor will automatically invoke OpenGround tools when relevant: 
You: How do I fetch data in React?

Cursor: Let me check the React documentation...
[Calls mcp__openground__search_documents_tool]

According to the React documentation:
...

​
Explicit Requests

You can explicitly ask Cursor to search documentation: 
You: Search openground for FastAPI routing examples

Cursor: [Searches FastAPI documentation using OpenGround]

​
Code Context + Documentation

Cursor can combine your code context with OpenGround documentation: 
You: I'm using this FastAPI route, is this the correct pattern?
[paste code]

Cursor: [Analyzes your code + searches FastAPI docs for best practices]

​
Platform-Specific Configuration

​
macOS

No special configuration needed. OpenGround should work out of the box after installation.

​
Linux

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

# Reload shell
source ~/.bashrc
Verify command is available: 
which openground-mcp

​
Windows

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

​
Advanced Configuration

​
Using Specific Python Environment

If you need to use a specific Python environment: 
{
  "mcpServers": {
    "openground": {
      "command": "/path/to/venv/bin/openground-mcp"
    }
  }
}

​
Environment Variables

You can pass environment variables to the MCP server: 
{
  "mcpServers": {
    "openground": {
      "command": "openground-mcp",
      "env": {
        "OPENGROUND_CONFIG": "/custom/path/config.json"
      }
    }
  }
}

​
Multiple OpenGround Instances

Run separate OpenGround instances with different configurations: 
{
  "mcpServers": {
    "openground-work": {
      "command": "/path/to/work-venv/bin/openground-mcp",
      "env": {
        "OPENGROUND_CONFIG": "~/.openground-work/config.json"
      }
    },
    "openground-personal": {
      "command": "/path/to/personal-venv/bin/openground-mcp",
      "env": {
        "OPENGROUND_CONFIG": "~/.openground-personal/config.json"
      }
    }
  }
}

​
Troubleshooting

​
Configuration Not Applied

1

Verify File Location

Confirm mcp.json is in the correct directory for your platform
2

Check JSON Syntax

Validate JSON using a linter or:
python -m json.tool ~/.cursor/mcp.json
3

Restart Cursor Completely

Quit Cursor entirely (not just close window), then restart

​
Invalid JSON Error

If Cursor reports invalid JSON:
  1. Restore from backup: 
    cp ~/.cursor/mcp.json.backup.YYYYMMDD_HHMMSS ~/.cursor/mcp.json
  2. Re-run the installer: 
    openground install-mcp --cursor

​
Permission Denied

If the installer reports permission errors: 
# Linux/macOS
chmod 644 ~/.cursor/mcp.json

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

​
Command Not Found

If Cursor reports openground-mcp not found:
1

Verify Installation

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

Use Full Path

Edit mcp.json to use the full path:
{
  "mcpServers": {
    "openground": {
      "command": "/full/path/to/openground-mcp"
    }
  }
}
3

Restart Cursor

Completely quit and restart

​
No Search Results

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

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

​
Updating Configuration

To update your OpenGround configuration: 
# Re-run the installer (creates new backup)
openground install-mcp --cursor
The installer automatically:
  1. Creates a new timestamped backup
  2. Preserves existing MCP servers
  3. Updates only the OpenGround configuration

​
Next Steps

Add Libraries

Index more documentation sources

Configure Search

Customize embedding models and search behavior

MCP Overview

Learn more about MCP architecture

Custom Agents

Use with other MCP-compatible clients

Build docs developers (and LLMs) love

Get started for freeTalk to us