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://your-server.com \
  -- npx opuscode-mcp

Global install

npm install -g opuscode-mcp

Manual Configuration

Claude Code

Add to your Claude Code MCP config (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "OpusCode": {
      "command": "npx",
      "args": ["opuscode-mcp"],
      "env": {
        "OPUSCODE_API_KEY": "your_key",
        "OPUSCODE_URL": "https://your-server.com"
      }
    }
  }
}

Cursor

Add to Cursor MCP settings (.cursor/mcp.json):

{
  "mcpServers": {
    "OpusCode": {
      "command": "npx",
      "args": ["opuscode-mcp"],
      "env": {
        "OPUSCODE_API_KEY": "your_key",
        "OPUSCODE_URL": "https://your-server.com"
      }
    }
  }
}

OpenCode

Add to your OpenCode config:

{
  "mcp": {
    "OpusCode": {
      "command": "npx",
      "args": ["opuscode-mcp"],
      "env": {
        "OPUSCODE_API_KEY": "your_key",
        "OPUSCODE_URL": "https://your-server.com"
      }
    }
  }
}

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 from the web.

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, GIF, BMP, SVG.

Environment Variables

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

Troubleshooting

"Error: Proxy request failed: 401"

Your OPUSCODE_API_KEY is missing or invalid. Make sure it's set in your environment or MCP config.

"Error: Proxy request failed: ECONNREFUSED"

The OpusCode proxy server is not running or OPUSCODE_URL points to the wrong address. Verify the server is up and the URL is correct.

"Error: File not found"

When using understand_image with a local file path, ensure the path is correct relative to where the MCP server process is running.

Tools not showing up

1. Restart your AI coding tool after adding the MCP config.
2. Check that npx opuscode-mcp runs without errors in your terminal.
3. Verify your MCP config JSON is valid.

License

MIT