mcp2skill

mcp2skill

Generate a ready‑to‑use "SKILL" folder from any MCP server. mcp2skill connects to a Model Context Protocol (MCP) server (stdio or Streamable HTTP), enumerates its tools, and emits a portable skill package containing:

• SKILL.md with clear, schema‑first usage guidance
• tools/*.json input schemas for each tool
• scripts/call-tool.js helper to invoke tools by name
• mcp-config.json capturing how to reconnect to the MCP server

This lets you install and reuse MCP tools as a standalone skill in other agent setups or workflows, without guessing inputs or wiring.

Requirements

• Node.js 18+

Usage

The CLI discovers tools from an MCP server and writes a self‑contained skill directory.

npx mcp2skill \
  --skill-name <skill name> \
  --mcp-name <mcp server name> \
  --transport <http|sse|stdio> \
  --out-dir <output root> \
  [URL or -- <command> [args...]]

Options

• --skill-name (required): Name of the skill folder to create.
• --mcp-name (required): Human‑friendly MCP server name recorded in SKILL.md.
• --transport (required): stdio or http (see note on sse below).
• --out-dir (required): Directory where the skill folder is created.
• --env KEY=VALUE (repeatable, stdio only): Environment variables for the spawned MCP server process.
• --header 'Key: Value' (repeatable, http/sse only): Placeholder for future header support. See limitations.

Notes

• For stdio, pass the command after --. You may repeat --env KEY=VALUE to inject environment variables.
• For http, pass exactly one URL positional argument.
• The CLI validates argument combinations and will refuse ambiguous inputs.

What gets generated

Given --out-dir ~/.claude/skills and --skill-name my-skill, the CLI writes:

~/.claude/skills/my-skill/
├─ SKILL.md              # Usage protocol and checklist
├─ mcp-config.json       # How to connect to the MCP server
├─ scripts/
│  └─ call-tool.js       # Helper to invoke tools by name
└─ tools/
   ├─ <toolA>.json       # JSON Schema for <toolA> input
   └─ <toolB>.json       # JSON Schema for <toolB> input

Examples

• Generate a skill from a local stdio server:

npx mcp2skill \
  --skill-name local-stdio-skill \
  --mcp-name local-stdio \
  --transport stdio \
  --out-dir ~/.claude/skills \
  -- node ./server/example-mcp.js

• Generate a skill from a Streamable HTTP server:

npx mcp2skill \
  --skill-name http-skill \
  --mcp-name http-demo \
  --transport http \
  --out-dir ~/.claude/skills \
  http://localhost:3000/mcp

How it works

• Discovers tools via the MCP client (@modelcontextprotocol/sdk) using:
  • StdioClientTransport for local/stdio servers
  • StreamableHTTPClientTransport for HTTP servers
• Writes tools/*.json from each tool’s inputSchema
• Emits SKILL.md with a schema‑first protocol and safety checklist
• Bundles scripts/call-tool.js that uses mcp-config.json to connect and call tools

Known limitations

• SSE: Although the CLI accepts --transport sse, the current client only connects via stdio or Streamable HTTP. SSE fallback is not implemented.
• HTTP headers: --header is accepted by the CLI but not yet persisted in mcp-config.json or applied by the client transport. If you need auth, prefer stdio or run your MCP server without custom headers for now.

License

mcp2skill is MIT licensed.