mcp-installer

justinlevinedotme/mcp-installer

DevOps

1 installs

About

SKILL.md

mcp-installer

justinlevinedotme/mcp-installer

DevOps

1 installs

About

Find, install, and configure MCP servers.

SKILL.md

Find, install, and configure MCP servers for OpenCode.

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 in the documentation section.

5. Setup (if needed)

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

Question Tool Usage

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

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

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

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

You need...	Read this file
All config options (local, remote, oauth, env vars)	`references/configuration.md`
Common MCP server examples	`references/examples.md`
Troubleshooting issues	`references/troubleshooting.md`

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

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

Field	Required	Purpose
`name`	Yes	MCP identifier (key in config)
`url`	No	Source URL
`type`	Yes	`local` or `remote`
`auth`	Yes	`oauth`, `api-key`, or `none`
`description`	Yes	One-liner for catalog
`tags`	No	Array of category tags

About

SKILL.md

About

Find, install, and configure MCP servers.

SKILL.md

Find, install, and configure MCP servers for OpenCode.

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 in the documentation section.

5. Setup (if needed)

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

Question Tool Usage

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

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

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

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

You need...	Read this file
All config options (local, remote, oauth, env vars)	`references/configuration.md`
Common MCP server examples	`references/examples.md`
Troubleshooting issues	`references/troubleshooting.md`

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

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

Field	Required	Purpose
`name`	Yes	MCP identifier (key in config)
`url`	No	Source URL
`type`	Yes	`local` or `remote`
`auth`	Yes	`oauth`, `api-key`, or `none`
`description`	Yes	One-liner for catalog
`tags`	No	Array of category tags