skills-mcp-server

A small Model Context Protocol (MCP) server that exposes Cursor-style skill packs (SKILL.md trees) to any MCP client. It uses the official TypeScript SDK and supports:

• stdio — local subprocess mode (typical for Cursor / Claude Desktop spawning a command).
• Streamable HTTP — remote mode on POST /mcp (stateless), MCP 2025-03-26+.
• Legacy SSE — GET /sse + POST /messages?sessionId=... for clients (including many Cursor remote setups) that expect the older HTTP+SSE transport.

This package is client-agnostic: anything that speaks MCP can use it.

Features (MCP surfaces)

Surface	Purpose
Resources	skills://skill/{skillId} — discover via template listing; bodies are Markdown.
Tools	list_skills, get_skill, search_skills
Prompts	skill_context — wraps a skill in a user message

Skill ids are the POSIX path from SKILLS_ROOT to the folder containing SKILL.md (root-level file uses id _root).

Quick start (local stdio)

npm install
npm run build

Default skills/ includes packs copied from .cursor/skills in this repo. Add more folders with SKILL.md as needed. Run:

npx skills-mcp-server
# or: node dist/main.js

In Cursor MCP settings, use command-based config with MCP_TRANSPORT unset or stdio:

{
  "mcpServers": {
    "skills": {
      "command": "node",
      "args": ["C:/absolute/path/to/skills-mcp-server/dist/main.js"],
      "env": {
        "SKILLS_ROOT": "C:/absolute/path/to/your/skills"
      }
    }
  }
}

Remote (hosted — Cursor without local stdio)

Use HOSTING_AND_CURSOR.md for free-tier hosts (Render, Railway, Fly, Koyeb, etc.), env vars, and Cursor mcp.json with url + headers.

Endpoints (same host, HTTPS):

• Streamable HTTP: https://your-host/mcp
• Legacy SSE (often best for Cursor remote): https://your-host/sse (messages go to /messages)

Health: GET https://your-host/health. Env reference: env.example.

Claude / other clients

Any MCP client that supports stdio or Streamable HTTP can attach the same server. Configure the vendor’s “remote MCP” or “HTTP MCP” entry with your HTTPS URL and bearer token if enabled.

Documentation

• HOSTING_AND_CURSOR.md — free hosting, env vars, Cursor remote MCP (url / SSE vs streamable).
• DEPLOYMENT.md — Docker, Compose, reverse proxy, operational checklist.

License

MIT.