Mcp Installer

MCP Installer

Find, install, and configure MCP servers for OpenCode.

<workflow>

1. Search for MCP Server

Check local catalog first (quick check for already-documented MCPs):

python3 ~/.config/opencode/skill/mcp-installer/scripts/list_mcps.py

If not found locally, search online:

• websearch("MCP server for [capability]")
• webfetch("https://github.com/modelcontextprotocol/servers")
• Check npm: @modelcontextprotocol/server-*
• Check the MCP spec repo: https://github.com/modelcontextprotocol

2. Read MCP Details

For relevant matches, read the full MCP file:

references/mcps/<name>.md

Contains installation config, setup, features, and links.

3. Configure

Add the MCP config to user's opencode.json.

4. Document New MCPs

If you discovered a new MCP server online, you MUST document it for future reference in references/mcps/<name>.md using the template below.

5. Setup (if needed)

• OAuth: Run opencode mcp auth <server-name>
• API keys: Set environment variables
• Other: Follow MCP-specific setup steps

</workflow>

<question_tool>

Batching: Use the question tool for 2+ related questions. Single questions → plain text.

Syntax: header ≤12 chars, label 1-5 words, add "(Recommended)" to default.

When to ask: Multiple MCPs match the need, or setup requires OAuth/API keys.

</question_tool>

<configuration>

Local MCP

{
  "mcp": {
    "name": {
      "type": "local",
      "command": ["npx", "-y", "@package/name"]
    }
  }
}

Remote MCP

{
  "mcp": {
    "name": {
      "type": "remote",
      "url": "https://example.com/mcp"
    }
  }
}

MCP Tool Management

MCPs expose tools. Control via the permission section using the tool name (usually the MCP name):

Global/Agent Permission:

{
  "permission": {
    "my-mcp": "deny",          // Disable all tools for this MCP
    "my-mcp*": "deny"          // Wildcard support
  }
}

Pattern-based control:

{
  "permission": {
    "my-mcp": {
      "safe_tool": "allow",
      "risky_tool": "ask",
      "*": "deny"
    }
  }
}

Legacy Configuration

Agents may occasionally work on legacy projects using outdated configuration fields (e.g., tools:). You MUST correct these to the modern permission: system when encountered.

OAuth

Remote MCPs with OAuth auto-authenticate:

opencode mcp auth <server-name>

Check status: opencode mcp list

</configuration>

<reference_files>

Note: The local catalog (list_mcps.py) is a cache of discovered MCPs, not a complete list. SHOULD always search online if you don't find a match locally.

</reference_files>

<documenting_new_mcps>

When discovering new MCP servers, you MUST document them:

Location: references/mcps/<name>.md

Template:

---
name: mcp-name
url: https://github.com/org/repo
type: local|remote
auth: oauth|api-key|none
description: One-line description
tags: [tag1, tag2]
---
# Display Name

Brief description.

## Installation

\`\`\`jsonc
{
  "mcp": {
    "name": {
      "type": "remote",
      "url": "https://example.com/mcp"
    }
  }
}
\`\`\`

## Setup

Steps for auth, env vars, etc.

## Features

- Feature 1
- Feature 2

## Links

- [GitHub](url)

Then run: python3 scripts/list_mcps.py to verify.

Frontmatter Fields

</documenting_new_mcps>

MCP Configuration Reference

<config_structure>

MCP servers are configured in opencode.json under the mcp key:

{
  "mcp": {
    "mcp-name": {
      // config here
    }
  }
}

</config_structure>

<local_mcp>

Local MCP Servers

Run a local process as an MCP server.

{
  "type": "local",
  "command": ["npx", "-y", "@package/name", "args"],
  "environment": {
    "VAR": "{env:VAR}"
  },
  "enabled": true,
  "timeout": 5000
}

• MUST use array format for command (not string)
• SHOULD set timeout for slow-starting servers
• MAY use {env:VAR} syntax for environment variables

</local_mcp>

<remote_mcp>

Remote MCP Servers

Connect to a remote MCP endpoint.

{
  "type": "remote",
  "url": "https://example.com/mcp",
  "headers": {
    "Authorization": "Bearer {env:API_KEY}"
  },
  "oauth": {},
  "enabled": true,
  "timeout": 5000
}

• MUST include full URL with protocol
• SHOULD use {env:VAR} for secrets in headers
• MAY use oauth: {} to enable automatic OAuth

</remote_mcp>

<oauth>

OAuth Configuration

Automatic (most servers):

opencode mcp auth server-name

Pre-registered credentials:

{
  "oauth": {
    "clientId": "{env:CLIENT_ID}",
    "clientSecret": "{env:CLIENT_SECRET}",
    "scope": "tools:read"
  }
}

Disable OAuth:

{
  "oauth": false
}

• MUST run opencode mcp auth after adding OAuth-enabled servers
• SHOULD use environment variables for credentials

</oauth>

<tool_management>

Tool Visibility

Control which MCP tools are available:

{
  "tools": {
    "my-mcp": false,
    "my-mcp*": false
  },
  "agent": {
    "my-agent": {
      "tools": {
        "my-mcp": true
      }
    }
  }
}

• SHOULD disable high-context MCPs globally, enable per-agent
• MAY use wildcards (*) to match multiple tools

</tool_management>

<environment_variables>

Environment Variables

Use {env:VAR_NAME} syntax in config. Set variables via:

export VAR_NAME=value

Or in .env file in project root.

• MUST NOT commit secrets to config files
• SHOULD use .env for project-specific variables

</environment_variables>

Common MCP Servers

<context7>

Context7 - Documentation Search

Remote server for searching library/framework docs. Requires API key.

{
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
      }
    }
  }
}

• MUST set CONTEXT7_API_KEY environment variable

</context7>

<gh_grep>

gh_grep - GitHub Code Search

Remote server for searching GitHub code. No auth required.

{
  "mcp": {
    "gh_grep": {
      "type": "remote",
      "url": "https://mcp.grep.app"
    }
  }
}

</gh_grep>

<sentry>

Sentry - Error Tracking

Remote server with OAuth authentication.

{
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}
    }
  }
}

• MUST run opencode mcp auth sentry after adding

</sentry>

<filesystem>

Filesystem - Local File Access

Local server for file operations.

{
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/allowed/path"
      ]
    }
  }
}

• MUST specify allowed paths as arguments
• SHOULD restrict to project directories

</filesystem>

<github>

GitHub - Repository API

Local server for GitHub API access. High context usage.

{
  "mcp": {
    "github": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
      "environment": {
        "GITHUB_TOKEN": "{env:GITHUB_TOKEN}"
      }
    }
  }
}

• MUST set GITHUB_TOKEN environment variable
• SHOULD disable globally and enable per-agent to manage context

</github>

<finding_more>

Finding More Servers

• Official registry: https://github.com/modelcontextprotocol/servers
• npm packages: @modelcontextprotocol/server-*
• This skill's catalog: references/mcps/*.md

</finding_more>

Brave Search MCP

Web and local search using Brave Search API.

Installation

{
  "mcp": {
    "brave-search": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-brave-search"],
      "environment": {
        "BRAVE_API_KEY": "{env:BRAVE_API_KEY}"
      }
    }
  }
}

Setup

1. Get API key from https://search.brave.com/api 2. Set BRAVE_API_KEY environment variable

Free tier: 2,000 queries/month

Usage

"Search for latest TypeScript 5.0 features using brave-search"

"Find tutorials about React hooks with brave-search"

Links

• GitHub

Chrome DevTools MCP

Official Chrome DevTools server for debugging, performance analysis, and automation.

Installation

{
  "mcp": {
    "chrome-devtools": {
      "type": "local",
      "command": ["npx", "-y", "chrome-devtools-mcp@latest"]
    }
  }
}

Setup

No authentication required. Chrome installs on first use.

Usage

"Check the performance of https://example.com using chrome-devtools"

"Debug network requests and console errors with chrome-devtools"

Options

{
  "command": [
    "npx",
    "-y",
    "chrome-devtools-mcp@latest",
    "--headless",
    "--channel=canary"
  ]
}

Links

• GitHub
• npm

Context7

Search documentation with AI-powered semantic search.

Installation

{
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
      }
    }
  }
}

Setup

1. Sign up at https://context7.com 2. Get API key from dashboard 3. Set CONTEXT7_API_KEY environment variable

Usage

"Search Cloudflare Workers docs using context7"

Links

• Website

Figma MCP

Official Figma server for design-to-code workflows.

Installation

Remote:

{
  "mcp": {
    "figma": {
      "type": "remote",
      "url": "https://mcp.figma.com/mcp",
      "oauth": {}
    }
  }
}

Desktop (local): Runs at http://127.0.0.1:3845/mcp when enabled in Figma desktop app.

Setup

Remote

opencode mcp auth figma

Desktop

1. Open Figma desktop app 2. Enable Dev Mode (Shift+D) 3. In MCP server section, click "Enable desktop MCP server"

Usage

"Generate code from my Figma selection using figma MCP"

"Extract design tokens and variables with figma"

Features

• Generate code from selected frames
• Extract design context (variables, components, layout)
• Retrieve FigJam and Make resources
• Code Connect integration

Links

• Docs
• Developer docs

Grep by Vercel (gh_grep)

Search code from millions of GitHub repositories.

Installation

{
  "mcp": {
    "gh_grep": {
      "type": "remote",
      "url": "https://mcp.grep.app"
    }
  }
}

Setup

No authentication required.

Usage

"Find examples of React hooks using gh_grep"

Links

• Website

GitHub MCP

Full GitHub API access.

⚠️ High context usage - use per-agent config.

Installation

{
  "mcp": {
    "github": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
      "environment": {
        "GITHUB_TOKEN": "{env:GITHUB_TOKEN}"
      }
    }
  }
}

Setup

1. Create token at https://github.com/settings/tokens 2. Set GITHUB_TOKEN environment variable

Usage

"List open PRs using github"

Context Management

Disable globally, enable per-agent:

{
  "tools": {
    "github": false
  },
  "agent": {
    "github-agent": {
      "tools": {
        "github": true
      }
    }
  }
}

Links

• GitHub

HubSpot MCP

Official HubSpot server for CRM data access.

⚠️ Beta - Public beta, subject to beta terms.

Installation

{
  "mcp": {
    "hubspot": {
      "type": "remote",
      "url": "https://api.hubspot.com/mcp",
      "oauth": {}
    }
  }
}

Setup

opencode mcp auth hubspot

Requires HubSpot app with MCP server enabled.

Usage

"Query HubSpot CRM data using hubspot MCP"

"Create a contact in HubSpot with hubspot"

Features

• Access CRM data (contacts, deals, companies)
• Object metadata retrieval
• CRUD operations on records
• Integration with Smart CRM

Links

• Docs
• Integration guide

Linear MCP

Linear issue tracking integration.

⚠️ Archived - This project is archived and read-only as of July 2025.

Installation

{
  "mcp": {
    "linear": {
      "type": "local",
      "command": ["node", "/path/to/linear-mcp/build/index.js"],
      "environment": {
        "LINEAR_API_KEY": "{env:LINEAR_API_KEY}"
      }
    }
  }
}

Setup

1. Get Linear API key 2. Build from source: bun install && bun run build 3. Set LINEAR_API_KEY environment variable

Usage

"Create a Linear issue using linear MCP"

"Search Linear issues with linear"

Links

• GitHub (archived)

Notion MCP

Official Notion server for workspace access.

Installation

{
  "mcp": {
    "notion": {
      "type": "remote",
      "url": "https://notion-mcp.notion.so",
      "oauth": {}
    }
  }
}

Setup

opencode mcp auth notion

Opens Notion OAuth authorization flow.

Usage

"Create a page in Notion using notion MCP"

"Search my Notion workspace with notion"

Links

• Docs

Playwright MCP

Official Microsoft Playwright server for browser automation.

Installation

{
  "mcp": {
    "playwright": {
      "type": "local",
      "command": ["npx", "@playwright/mcp@latest"]
    }
  }
}

Setup

No authentication required. Browser installs on first use.

Usage

"Navigate to example.com and take a screenshot using playwright"

"Fill out the login form with playwright"

Options

{
  "command": [
    "npx",
    "@playwright/mcp@latest",
    "--headless",
    "--browser", "firefox"
  ]
}

Links

• GitHub
• npm

Postgres MCP

PostgreSQL schema inspection and read-only queries.

Installation

{
  "mcp": {
    "postgres": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://user:password@localhost:5432/dbname"
      ]
    }
  }
}

Setup

Provide PostgreSQL connection string in command args.

⚠️ Use env var for credentials:

{
  "command": [
    "npx",
    "-y",
    "@modelcontextprotocol/server-postgres",
    "{env:DATABASE_URL}"
  ]
}

Usage

"Inspect database schema with postgres MCP"

"Query all users from postgres"

Links

• GitHub

Redis MCP

Official Redis server for data management and search.

Installation

{
  "mcp": {
    "redis": {
      "type": "local",
      "command": ["npx", "-y", "@redis/mcp-redis"],
      "environment": {
        "REDIS_URI": "redis://localhost:6379"
      }
    }
  }
}

Setup

Set REDIS_URI to your Redis connection string.

Usage

"Query Redis for session data using redis MCP"

"Search vector embeddings in Redis with redis"

Links

• GitHub
• Blog

Sentry

Interact with Sentry projects and issues.

Installation

{
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}
    }
  }
}

Setup

opencode mcp auth sentry

Opens browser for OAuth authorization.

Usage

"Show latest unresolved issues using sentry"

Links

• Docs

Slack MCP

Official Slack server for workspace access.

⚠️ Limited availability - Currently in partner rollout only.

Installation

{
  "mcp": {
    "slack": {
      "type": "remote",
      "url": "https://slack-mcp.slack.dev",
      "oauth": {}
    }
  }
}

Setup

opencode mcp auth slack

Requires Slack partner approval for access.

Usage

"Search Slack messages using slack MCP"

"Send a message to a channel with slack"

Features

• Search messages and files
• Send messages to channels
• Read channels and threads
• Manage canvases
• Fetch user profiles

Links

• Docs

SQLite MCP

SQLite database queries and management.

Installation

{
  "mcp": {
    "sqlite": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@modelcontextprotocol/server-sqlite",
        "--db-path",
        "/path/to/database.db"
      ]
    }
  }
}

Setup

Provide path to SQLite database file in command args.

Usage

"Query all users from sqlite"

"Create a new table in the database using sqlite"

Links

• GitHub

Stripe MCP

Official Stripe server for payment API integration.

Installation

Remote:

{
  "mcp": {
    "stripe": {
      "type": "remote",
      "url": "https://mcp.stripe.com",
      "oauth": {}
    }
  }
}

Local:

{
  "mcp": {
    "stripe": {
      "type": "local",
      "command": ["npx", "-y", "@stripe/mcp", "--tools=all"],
      "environment": {
        "STRIPE_SECRET_KEY": "{env:STRIPE_SECRET_KEY}"
      }
    }
  }
}

Setup

Remote:

opencode mcp auth stripe

Local: Set STRIPE_SECRET_KEY environment variable.

Usage

"Create a Stripe payment link using stripe MCP"

"List recent PaymentIntents with stripe"

Features

• Account, customer, and product management
• Payment links and PaymentIntents
• Invoices and subscriptions
• Refunds and disputes
• Search Stripe docs and resources

Links

• Docs
• GitHub

Supabase MCP

Official Supabase server for database queries, schema management, and project operations.

Installation

{
  "mcp": {
    "supabase": {
      "type": "local",
      "command": ["npx", "-y", "@supabase/mcp-server"],
      "environment": {
        "SUPABASE_ACCESS_TOKEN": "{env:SUPABASE_ACCESS_TOKEN}"
      }
    }
  }
}

Setup

1. Get access token from Supabase dashboard 2. Set SUPABASE_ACCESS_TOKEN environment variable

Usage

"Query users table from Supabase using supabase MCP"

"Create a new table in Supabase with supabase"

Links

• GitHub
• Docs

Troubleshooting

<mcp_not_appearing>

MCP Not Appearing

1. Check "enabled": true in MCP config 2. Verify not disabled in "tools" section 3. Test connectivity:

# Remote
curl https://mcp.example.com/mcp

# Local
npx -y @package/name

• MUST restart OpenCode after config changes

</mcp_not_appearing>

<auth_failures>

Authentication Failures

opencode mcp list          # Check status
opencode mcp debug name    # Debug specific server
opencode mcp logout name   # Clear credentials
opencode mcp auth name     # Re-authenticate

• SHOULD clear and re-auth if tokens are stale

</auth_failures>

<oauth_issues>

OAuth Issues

• Verify server supports RFC 7591 (Dynamic Client Registration)
• Use pre-registered OAuth if automatic fails
• Check browser console for popup errors
• Clear tokens manually:

rm ~/.local/share/opencode/mcp-auth.json

• SHOULD use pre-registered credentials for enterprise servers

</oauth_issues>

<context_limits>

Context Limit Issues

MCPs add tool definitions to context. Solutions:

• Disable unused: "tools": { "my-mcp": false }
• Enable per-agent: agent.my-agent.tools
• Use lightweight alternatives (gh_grep vs github)

• SHOULD prefer remote MCPs over local for lower context
• SHOULD disable high-context MCPs globally

</context_limits>

<env_variables>

Environment Variable Issues

echo $MY_VAR              # Check if set
export MY_VAR=value       # Set in shell

Or add to .env file in project root.

• MUST set variables before starting OpenCode
• SHOULD use .env for project-specific values

</env_variables>

<local_command_issues>

Local Command Issues

which npx                 # Check in PATH
npx -y @package/name      # Test manually

• SHOULD use absolute paths if PATH issues persist
• MAY increase timeout for slow-starting servers

</local_command_issues>

<remote_connection>

Remote Connection Issues

curl https://mcp.example.com/mcp  # Test URL

Increase timeout if slow:

{
  "timeout": 30000
}

• SHOULD check firewall/proxy settings
• MAY need VPN for enterprise servers

</remote_connection>