OpusCode MCP

MCP (Model Context Protocol) server that provides web search and image understanding tools for AI coding agents — Claude Code, Cursor, OpenCode, and more.

Quick Install

Claude Code (recommended)

claude mcp add -s user OpusCode \
  --env OPUSCODE_API_KEY=your_key \
  --env OPUSCODE_URL=https://claude.opuscode.pro \
  -- npx -y opuscode-mcp

Global install

npm install -g opuscode-mcp

Manual Configuration

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "OpusCode": {
      "command": "npx",
      "args": ["-y", "opuscode-mcp"],
      "env": {
        "OPUSCODE_API_KEY": "your_key",
        "OPUSCODE_URL": "https://claude.opuscode.pro"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "OpusCode": {
      "command": "npx",
      "args": ["-y", "opuscode-mcp"],
      "env": {
        "OPUSCODE_API_KEY": "your_key",
        "OPUSCODE_URL": "https://claude.opuscode.pro"
      }
    }
  }
}

OpenCode

Add to your OpenCode config:

{
  "mcp": {
    "OpusCode": {
      "type": "local",
      "command": ["npx", "-y", "opuscode-mcp"],
      "environment": {
        "OPUSCODE_API_KEY": "your_key",
        "OPUSCODE_URL": "https://claude.opuscode.pro"
      },
      "enabled": true
    }
  }
}

Tools

| Tool | Description | |---|---| | web_search | Search the web for real-time information. Best with 3–5 keywords. | | understand_image | Analyze images using AI. Accepts URLs, local file paths, or base64 data URLs. |

Usage Examples

Web Search

Search for: "Node.js 22 new features 2025"

The web_search tool accepts a query string and returns structured search results.

Image Understanding

Prompt: "Describe this UI mockup and list all the components"
Image source: "./screenshot.png"

The understand_image tool accepts:

• prompt — What you want to know about the image
• image_source — One of:
  • An HTTP/HTTPS URL (https://example.com/image.png)
  • A local file path (./diagram.png or /home/user/photo.jpg)
  • A base64 data URL (data:image/png;base64,...)

Supported formats: JPEG, PNG, WebP. Max size: 15MB.

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | OPUSCODE_API_KEY | Yes | — | API key for authentication | | OPUSCODE_URL | No | http://localhost:3001 | OpusCode server URL |

Troubleshooting

"Error: Proxy request failed: 401"

Your OPUSCODE_API_KEY is missing or invalid.

"Error: Proxy request failed: ECONNREFUSED"

The server is not reachable. Check OPUSCODE_URL.

"Image too large"

Images must be under 15MB. Resize or compress before retrying.

Tools not showing up

1. Restart your AI coding tool after adding the MCP config.
2. Check that npx opuscode-mcp runs without errors.
3. In Claude Code, type /mcp to verify web_search and understand_image are listed.

License

MIT