harness-mcp

Add high-quality MCP servers to any AI harness. Start with OpenCode, extend to Claude Code, Cursor, and more.

Install

# Python (pip)
pip install harness-mcp

# Node.js (npm) — auto-installs Python deps
npm install -g harness-mcp

# Node.js (npx) — no install
npx harness-mcp list

# Single binary (no Python needed)
# Download from: https://github.com/suvenkatesh97/harness-mcp/releases

Quick Start

# See what's available
harness-mcp list

# Add a server
harness-mcp add github

# Add multiple
harness-mcp add github playwright brave-search

# Add all with a tag
harness-mcp add --tag browser

# Add with required env vars (will prompt interactively)
harness-mcp add slack

# Pass env vars for scripting
harness-mcp add slack --env SLACK_BOT_TOKEN=xoxb-your-token

# See what's configured
harness-mcp status

# Remove a server
harness-mcp remove github

Scope — Project vs Global

--scope controls where servers are written. Place it before or after the command:

# Project-scoped config (default) — ./opencode.jsonc
harness-mcp add docker

# Global config — ~/.config/opencode/opencode.json
harness-mcp --scope global add docker

# Also works after the command
harness-mcp status --scope global

Run harness-mcp status to see which config is in use.

Harness Support

Interactive Mode

pip install harness-mcp[interactive]
harness-mcp init

Commands

All commands support --scope project|global to choose where config is written.

Global Flags

• --harness - Target harness (opencode, claude, cursor). Auto-detected.
• --scope - project (default) or global
• --cwd - Working directory for project scope
• --dry-run - Preview changes without writing

Custom Catalog Entries

Add your own MCP servers without code changes:

# ~/.config/harness-mcp/catalog/my-servers.yaml
servers:
  - id: my-custom-server
    name: My Custom MCP Server
    description: Does something useful
    type: local
    command:
      - npx
      - -y
      - my-mcp-server
    env_vars:
      - name: API_KEY
        description: Your API key
        required: true
    tags:
      - custom

Or project-level: .harness-mcp/catalog/*.yaml

OpenCode Plugin

Use harness-mcp directly within OpenCode:

{
  "plugin": ["@harness-mcp/opencode-plugin"]
}

Then ask OpenCode to use harness_mcp_list or use harness_mcp_add to add github.

Built-in Catalog