Skills MCP Server

An MCP (Model Context Protocol) server that exposes your Claude Skills library as a discoverable, searchable, and composable skill registry. Designed for seamless integration with Tasklet (via HTTP/SSE) and local MCP hosts like OpenCode, Claude Desktop, and Cursor (via STDIO).

Background and Motivation

AI agent environments like Tasklet require configuring custom skills and prompts manually through their UI, typically one skill at a time. When managing a rich personal library of 100 to 200+ specialized engineering skills, adding them individually by hand is tedious, slow, and impossible to maintain as instructions evolve.

Furthermore, dumping dozens of skills directly into an agent's static context or system prompt wastes thousands of tokens per turn and causes prompt dilution.

This MCP server was built to eliminate that bottleneck:

1. Zero Manual Copy-Pasting: Point the server at your existing local skills folder and all skills are immediately available.

2. On-Demand Retrieval: Models dynamically search (search_skills) and load (get_skill) only the relevant skill instructions when a task calls for them, keeping context windows lean.

3. Universal Portability: By implementing the standard Model Context Protocol (MCP SDK 2.2.0), the same local skills library can be accessed across Tasklet, Claude Desktop, Claude.ai Web, Cursor, Windsurf, Zed, Neovim, and CLI agents.

Related MCP server: Skillz

Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
                        SKILL SOURCE (Canonical)
                 Local Skills Directory (~/.claude/skills)
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
       ┌─────────────┐                   ┌─────────────┐
       │  LOCAL MODE │                   │ REMOTE MODE │
       │  (STDIO)    │                   │  (HTTP+SSE) │
       └──────┬──────┘                   └──────┬──────┘
              │                                 │
       ┌──────┴──────┐                   ┌──────┴──────┐
       ▼             ▼                   ▼             ▼
   OpenCode    Claude Desktop        Tasklet      Other MCP
   Cursor      Other Local           Cloud         Hosts
   Hosts       Hosts                 Agent

Features

• Dynamic Discovery: Automatically finds all skills in your skills directory

• Smart Search: Natural language search across names, descriptions, tags, triggers, and categories

• Multi-Skill Loading: Retrieve multiple skills at once for complex tasks

• Profiles/Bundles: Composable skill profiles for common workflows (product-builder, senior-engineer, researcher, designer)

• MCP Native: Full support for Tools, Resources, and Prompts

• Dual Transport: STDIO for local, HTTP+SSE for remote (Tasklet)

• Secure: Optional Bearer token auth for remote deployments

• No Duplication: Reads your existing skills in-place; no copying required

Configuring Your Skills Directory

You can point the server to any local directory containing skills:

• Windows: C:\Users\<username>\.claude\skills or D:\projects\my-skills

• macOS: /Users/<username>/.claude/skills

• Linux: /home/<username>/.claude/skills

There are three ways to configure your skills path:

1. Command Line Flag (simplest):

   python -m src.server --skill-root "path/to/your/skills"

2. Configuration File (config.json):

   {
     "skill_root": "/path/to/your/skills",
     "profile_dir": "profiles",
     "port": 8080
   }

3. Environment Variable (.env or shell):

   export SKILL_ROOT="/path/to/your/skills"

Client Setup

Cline & Roo Code Setup

Cline and Roo Code can launch the server over MCP STDIO from their shared cline_mcp_settings.json configuration. Clone the repository, install its dependencies, and use the repository's src.server entry point:

{
  "mcpServers": {
    "skills": {
      "command": "python",
      "args": [
        "-m",
        "src.server",
        "--transport",
        "stdio",
        "--skill-root",
        "C:/Users/<username>/.claude/skills"
      ],
      "cwd": "C:/path/to/Skills_MCP_Server"
    }
  }
}

On macOS or Linux, replace the Windows paths with absolute paths such as /Users/<username>/.claude/skills and /path/to/Skills_MCP_Server. If you prefer uv, replace the command and arguments with:

{
  "command": "uv",
  "args": [
    "run",
    "--directory",
    "/path/to/Skills_MCP_Server",
    "python",
    "-m",
    "src.server",
    "--transport",
    "stdio",
    "--skill-root",
    "/Users/<username>/.claude/skills"
  ]
}

The issue description refers to python -m skills_mcp_server, but this repository currently exposes src.server and does not define a skills_mcp_server module or console script. Keep src.server in the configuration unless the package entry point is added in a separate change.

After saving cline_mcp_settings.json, reload the MCP servers from the Cline or Roo Code MCP panel, or restart the editor if the server remains stopped. The connection is ready when the server is shown as connected and the tools list includes list_skills, search_skills, and get_skill (along with the other Skills MCP tools). Use an absolute cwd and --skill-root; do not put credentials or API keys in this configuration.

1. Claude Desktop (Local STDIO)

Add to %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "skills": {
      "command": "python",
      "args": [
        "-m", "src.server",
        "--transport", "stdio",
        "--skill-root", "C:\\Users\\<username>\\.claude\\skills"
      ],
      "cwd": "L:\\My Innovations\\Skills_MCP_Server"
    }
  }
}

Restart Claude Desktop. All 10 skills tools are immediately available in chats.

2. Claude Browser Version (Claude.ai Web)

Because Claude.ai runs in the cloud, it cannot directly reach localhost:8080 on your physical workstation. Connect it via a secure SSE tunnel:

Step 1: Start the HTTP server pointing to your skills folder

cd L:\My Innovations\Skills_MCP_Server
python -m src.server --transport http --host 0.0.0.0 --port 8080 --skill-root "C:\Users\<username>\.claude\skills"

Step 2: Expose the server to the internet using an SSH tunnel Run in a separate terminal:

ssh -R 80:localhost:8080 tinyfi.sh

(Alternatively, use ngrok http 8080 or Cloudflare Tunnel). This outputs a public URL: https://<tunnel-id>.tinyfi.sh.

Step 3: Connect inside Claude.ai (Browser)

1. Open Claude.ai in your browser.

2. Go to Settings -> Integrations / Connectors (or MCP settings).

3. Click Add Remote MCP Server.

4. Fill in the connection settings:

   • Name: my-skills

   • Transport: SSE

   • URL: https://<tunnel-id>.tinyfi.sh/mcp/sse

   • Authorization Header: Bearer <AUTH_TOKEN> (if auth is enabled)

5. Save. Claude in your web browser now has direct access to your local skills library.

Cursor Setup

1. Clone this repository, create .venv, and install the project dependencies as shown in Prerequisites. Use Python 3.11 or later for this configuration and the dependencies declared in pyproject.toml, including MCP SDK 2.2.0 or later.

2. Create .cursor/mcp.json in the project opened in Cursor, or use ~/.cursor/mcp.json for a global configuration. If the file already exists, merge the skills entry into its existing mcpServers object:

{
  "mcpServers": {
    "skills": {
      "type": "stdio",
      "command": "/path/to/Skills_MCP_Server/.venv/bin/python",
      "args": [
        "-P", "-m", "src.server",
        "--transport", "stdio",
        "--skill-root", "/path/to/skills"
      ],
      "env": {
        "PYTHONPATH": "/path/to/Skills_MCP_Server",
        "PROFILE_DIR": "/path/to/Skills_MCP_Server/profiles"
      }
    }
  }
}

3. Replace every /path/to value with an absolute path. On Windows, use the virtual environment's .venv/Scripts/python.exe and write paths with forward slashes or escaped backslashes (\\). PYTHONPATH locates the repository's src.server module, and -P prevents another project's src package from taking precedence. PROFILE_DIR locates the profiles even when Cursor opens a different project.

4. Save the file and restart Cursor. Enable skills from Customize and check Available Tools in the Agent/composer for list_skills, search_skills, and get_skill. Ask "Use list_skills to list my available skills" and inspect the tool response to verify the connection.

See the official Cursor MCP documentation for configuration details.

4. Windsurf IDE Setup

Windsurf connects to Skills MCP Server over STDIO or HTTP/SSE using its Cascade AI assistant.

Configuration File Location

Windsurf stores MCP server configurations in mcp_config.json:

• macOS / Linux: ~/.codeium/windsurf/mcp_config.json

• Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json (e.g. C:\Users\<username>\.codeium\windsurf\mcp_config.json)

To open or edit this file in Windsurf:

1. Open the Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows/Linux).

2. Run Windsurf: Configure MCP Servers (or click the hammer/plug icon in the Cascade panel and select Configure / View raw config).

3. If the directory or file does not exist, create the .codeium/windsurf/ directory and mcp_config.json file.

STDIO Configuration Example (Recommended)

Add Skills MCP Server under the top-level "mcpServers" key using your virtual environment Python:

macOS / Linux (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "skills": {
      "command": "/path/to/Skills_MCP_Server/.venv/bin/python",
      "args": [
        "-m",
        "src.server",
        "--transport",
        "stdio",
        "--skill-root",
        "/path/to/skills"
      ],
      "cwd": "/path/to/Skills_MCP_Server",
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Windows (%USERPROFILE%\.codeium\windsurf\mcp_config.json):

{
  "mcpServers": {
    "skills": {
      "command": "C:\\path\\to\\Skills_MCP_Server\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "src.server",
        "--transport",
        "stdio",
        "--skill-root",
        "C:\\Users\\<username>\\.claude\\skills"
      ],
      "cwd": "C:\\path\\to\\Skills_MCP_Server",
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Windows Path Notes:

• In JSON strings, Windows backslashes must be escaped with double backslashes (C:\\path\\to\\...) or written with forward slashes (C:/path/to/...).

• Point to the virtual environment binary at .venv\Scripts\python.exe.

• Always specify "cwd" pointing to your cloned Skills_MCP_Server repository root so Python can resolve the src package.

Remote HTTP / SSE Option

If running the standalone HTTP server (python -m src.server --transport http --port 8080), connect via Windsurf's serverUrl field:

{
  "mcpServers": {
    "skills": {
      "serverUrl": "http://localhost:8080/mcp/sse"
    }
  }
}

Reload & Verify Connection

1. Save mcp_config.json.

2. In the Cascade panel, click the Refresh button next to MCP servers (or restart Windsurf).

3. Confirm that skills shows a green connected status indicator.

4. Test with Cascade in chat: "List available skills using list_skills" or check the tools list to see all 10 MCP tools.

5. Zed Editor Setup

Zed integrates MCP servers via its Assistant panel using the context_servers setting.

Configuration File Location

Zed stores settings in settings.json:

• Linux & macOS: ~/.config/zed/settings.json (or ~/.zed/settings.json on macOS)

• Windows: %APPDATA%\Zed\settings.json (e.g. C:\Users\<username>\AppData\Roaming\Zed\settings.json)

To open this file in Zed:

1. Open the Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows/Linux).

2. Type and run zed: open settings (or press Cmd-, on macOS, Ctrl-, on Windows/Linux).

3. If creating a new file, initialize it with {}.

Preserving Existing Settings (Merge Guide)

Do not overwrite your existing settings.json. Instead, add or merge the "context_servers" object into your configuration.

macOS / Linux (~/.config/zed/settings.json):

{
  "context_servers": {
    "skills": {
      "command": "/path/to/Skills_MCP_Server/.venv/bin/python",
      "args": [
        "-m",
        "src.server",
        "--transport",
        "stdio",
        "--skill-root",
        "/path/to/skills"
      ],
      "env": {
        "PYTHONPATH": "/path/to/Skills_MCP_Server"
      }
    }
  }
}

Windows (%APPDATA%\Zed\settings.json):

{
  "context_servers": {
    "skills": {
      "command": "C:\\path\\to\\Skills_MCP_Server\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "src.server",
        "--transport",
        "stdio",
        "--skill-root",
        "C:\\Users\\<username>\\.claude\\skills"
      ],
      "env": {
        "PYTHONPATH": "C:\\path\\to\\Skills_MCP_Server"
      }
    }
  }
}

Merged Example with Pre-Existing Settings:

{
  "theme": "One Dark",
  "ui_font_size": 16,
  "context_servers": {
    "skills": {
      "command": "/path/to/Skills_MCP_Server/.venv/bin/python",
      "args": [
        "-m",
        "src.server",
        "--transport",
        "stdio",
        "--skill-root",
        "/path/to/skills"
      ],
      "env": {
        "PYTHONPATH": "/path/to/Skills_MCP_Server"
      }
    }
  }
}

Why PYTHONPATH in Zed? Unlike Windsurf, Zed's context_servers schema does not include a cwd (working directory) property. Setting "PYTHONPATH" in the "env" block ensures Python can locate and import the src package regardless of the project folder opened in Zed. Alternatively, install the package in editable mode (pip install -e . inside .venv).

Remote HTTP / SSE Option in Zed

If running the standalone HTTP/SSE server:

{
  "context_servers": {
    "skills": {
      "url": "http://localhost:8080/mcp/sse"
    }
  }
}

Reload & Verify Connection

1. Save settings.json (Zed automatically hot-reloads configuration files upon saving).

2. Open the Assistant panel (Cmd-Alt-B on macOS, Ctrl-Alt-B on Windows/Linux, or click the speech bubble in the right dock).

3. If Zed displays a Worktree Trust prompt for local MCP server execution, select Trust to authorize the server.

4. Verify server status under Settings -> AI -> MCP Servers (agent: open settings in the Command Palette).

5. In the Assistant conversation, test by asking: "Use the list_skills tool to search available skills."

6. Antigravity IDE / Gemini IDE

Add to your workspace mcp_config.json:

{
  "mcpServers": {
    "skills": {
      "command": "python",
      "args": ["-m", "src.server", "--transport", "stdio", "--skill-root", "C:\\path\\to\\skills"],
      "cwd": "L:\\My Innovations\\Skills_MCP_Server"
    }
  }
}

7. Neovim

Neovim connects to Skills MCP Server through MCP-compatible plugins, enabling your in-editor AI assistants to discover, search, and execute tools directly from your personal skills library. Popular plugins supporting MCP include:

• mcphub.nvim: A dedicated MCP client manager and gateway for Neovim. It runs a background hub process, parses standard servers.json configurations, provides an interactive management interface (:MCPHub), and serves tools to other plugins.

• codecompanion.nvim: An extensible AI coding assistant that supports LLM tool-calling and integrates with mcphub.nvim to expose MCP tools directly within :CodeCompanionChat.

• avante.nvim: An AI-powered code companion that dynamically integrates MCP tools and prompt slash commands via mcphub.nvim extensions.

Note on Configuration Syntax: Exact configuration syntax depends on the plugin and installed version. In the Neovim ecosystem, mcphub.nvim serves as the centralized server manager, while chat plugins like codecompanion.nvim and avante.nvim consume MCP tools through mcphub's Lua extension APIs. Below, separate configuration examples are provided for each setup.

STDIO Configuration (Local Process)

In STDIO mode, Neovim launches Skills MCP Server as a local child process communicating over standard input and standard output.

Conceptual Server Configuration

The MCP server requires the virtual-environment Python binary, the module entry point, standard I/O transport, and an explicit PYTHONPATH pointing to the repository root:

local project_root = "/absolute/path/to/Skills_MCP_Server"

local server_config = {
  command = project_root .. "/.venv/bin/python",
  args = {
    "-m",
    "src.server",
    "--transport",
    "stdio",
    "--skill-root",
    vim.fn.expand("~/.claude/skills"), -- Replace with your skills directory
  },
  env = {
    PYTHONPATH = project_root,
    PYTHONUNBUFFERED = "1",
  },
  cwd = project_root,
}

Adapting Configuration Parameters:

• project_root: Replace /absolute/path/to/Skills_MCP_Server with the absolute path to your cloned repository (e.g. /home/user/Skills_MCP_Server on Linux/macOS or C:/Users/user/Skills_MCP_Server on Windows).

• command: Points to the virtual-environment Python interpreter (.venv/bin/python or .venv/Scripts/python.exe on Windows). If using uv, you can alternatively use command = "uv" with args = { "run", "--directory", project_root, "python", "-m", "src.server", "--transport", "stdio", "--skill-root", "/path/to/skills" }.

• args: The repository's entry point is -m src.server. Specify --transport stdio and --skill-root pointing to your skills folder.

• env.PYTHONPATH: Required so Python can resolve the src package regardless of the current working directory in Neovim.

• cwd: Repository root where src/ and profiles/ reside.

Remote HTTP / SSE Configuration

Skills MCP Server natively provides a Server-Sent Events (SSE) endpoint for remote or persistent daemon access.

Endpoint:

http://localhost:8080/mcp/sse

1. Start the HTTP/SSE Server

From your repository root, run the server with --transport http:

cd /absolute/path/to/Skills_MCP_Server
source .venv/bin/activate       # On Windows: .venv\Scripts\activate
python -m src.server --transport http --host 127.0.0.1 --port 8080 --skill-root /path/to/skills

2. Verify the Server is Listening

Before connecting from Neovim, verify that the HTTP server is healthy and responding:

# Verify health endpoint (returns JSON status, skill count, and profile count)
curl -s http://localhost:8080/health

# Verify root metadata and registered endpoints
curl -s http://localhost:8080/

Expected health response:

{"status":"healthy","skills":42,"profiles":8,"version":"0.1.0"}

3. Configure HTTP/SSE in servers.json

Point your client configuration directly to the SSE endpoint:

{
  "mcpServers": {
    "skills": {
      "url": "http://localhost:8080/mcp/sse"
    }
  }
}

Authentication & Transport Limitations:

• If AUTH_TOKEN is configured on the server, include the bearer token in headers ("headers": { "Authorization": "Bearer <your-token>" }) or append it as a query parameter: http://localhost:8080/mcp/sse?token=<your-token>.

• Skills MCP Server implements MCP over Server-Sent Events (GET /mcp/sse for event streaming and POST /mcp/messages for client messages). Direct HTTP POST JSON-RPC calls to /mcp/rpc are rejected; ensure your client uses the SSE endpoint.

Plugin-Specific Setup Guides

A. mcphub.nvim (Central MCP Hub)

mcphub.nvim provides primary server lifecycle management for Neovim.

1. Configure Servers (~/.config/mcphub/servers.json):

   {
     "mcpServers": {
       "skills": {
         "command": "/absolute/path/to/Skills_MCP_Server/.venv/bin/python",
         "args": [
           "-m",
           "src.server",
           "--transport",
           "stdio",
           "--skill-root",
           "/absolute/path/to/skills"
         ],
         "env": {
           "PYTHONPATH": "/absolute/path/to/Skills_MCP_Server",
           "PYTHONUNBUFFERED": "1"
         },
         "cwd": "/absolute/path/to/Skills_MCP_Server"
       }
     }
   }

   (For HTTP/SSE, replace the command/args/env/cwd block with "url": "http://localhost:8080/mcp/sse").

2. Neovim Plugin Specification (lazy.nvim):

   {
     "ravitemer/mcphub.nvim",
     dependencies = {
       "nvim-lua/plenary.nvim",
     },
     build = "npm install -g mcp-hub@latest",
     config = function()
       require("mcphub").setup({
         port = 3000,
         config = vim.fn.expand("~/.config/mcphub/servers.json"),
       })
     end,
   }

B. codecompanion.nvim Integration

codecompanion.nvim integrates with mcphub.nvim to expose MCP tools to its chat strategy.

Neovim Plugin Specification (lazy.nvim):

{
  "olimorris/codecompanion.nvim",
  dependencies = {
    "nvim-lua/plenary.nvim",
    "nvim-treesitter/nvim-treesitter",
    "ravitemer/mcphub.nvim",
  },
  opts = {
    strategies = {
      chat = {
        tools = {
          ["mcp"] = {
            callback = function()
              return require("mcphub.extensions.codecompanion")
            end,
            description = "Call MCP servers for external tools and skill management",
            opts = {
              requires_approval = true,
            },
          },
        },
      },
    },
  },
}

C. avante.nvim Integration

avante.nvim dynamically injects active MCP server tools into the assistant's system prompt and registers tool handlers.

Neovim Plugin Specification (lazy.nvim):

{
  "yetone/avante.nvim",
  event = "VeryLazy",
  version = false,
  dependencies = {
    "nvim-lua/plenary.nvim",
    "MunifTanjim/nui.nvim",
    "ravitemer/mcphub.nvim",
  },
  opts = {
    system_prompt = function()
      local hub = require("mcphub").get_hub_instance()
      return hub and hub:get_active_servers_prompt() or ""
    end,
    custom_tools = function()
      return {
        require("mcphub.extensions.avante").mcp_tool(),
      }
    end,
  },
}

Connection Verification

Follow these steps to confirm your Neovim integration is working correctly:

1. Manual Server Verification:

   • STDIO: Verify that the process starts cleanly from a terminal:

     cd /absolute/path/to/Skills_MCP_Server
     .venv/bin/python -m src.server --transport stdio --skill-root /path/to/skills

     The process will idle waiting for JSON-RPC input on standard input without crashing or unexpected standard output errors.

   • HTTP/SSE: Confirm the server is reachable:

     curl -s http://localhost:8080/health

2. Plugin Discovery Verification:

   • In Neovim, execute:

     :MCPHub

   • Confirm that skills appears with an active/running status indicator.

   • Inspect the server details to verify that all 10 MCP tools are registered: list_skills, search_skills, get_skill, get_skills, list_profiles, get_profile, resolve_profile, refresh_skills, get_categories, get_skill_stats.

3. Execute a Tool Call:

   • In CodeCompanion (:CodeCompanionChat):

     "Use the list_skills tool to check available skills."

   • In Avante (:AvanteChat):

     "Search for fastapi skills using search_skills."

   • Confirm that the assistant executes the tool call and displays results from your skills library.

Neovim Troubleshooting

Cross-Platform Troubleshooting

When configuring Skills MCP Server across editors (Windsurf, Zed, Claude Desktop, Cursor, Neovim), refer to the following common issues and resolutions:

1. Windows Paths vs. Linux/macOS Paths

• JSON Escape Sequences: In JSON string values on Windows, single backslashes are interpreted as escape characters. Always escape backslashes with double backslashes (e.g. "C:\\Users\\user\\Skills_MCP_Server") or use forward slashes ("C:/Users/user/Skills_MCP_Server").

• Tilde Expansion: Paths containing ~ (e.g. ~/.venv/bin/python) are not expanded by JSON parsers. Always specify full absolute paths (e.g. /home/username/Skills_MCP_Server/... or /Users/username/...).

2. Python Executables, Virtual Environments, and Missing Dependencies

• System Python vs. Virtual Environment: Point directly to the virtual environment Python executable:

  • Linux / macOS: /path/to/Skills_MCP_Server/.venv/bin/python

  • Windows: C:\path\to\Skills_MCP_Server\.venv\Scripts\python.exe

• Missing Module Errors (No module named 'mcp'): Occurs when dependencies are not installed in the target Python environment. Run:

  cd /path/to/Skills_MCP_Server
  source .venv/bin/activate       # On Windows: .venv\Scripts\activate
  pip install -e .

3. Spaces in Paths and JSON Escaping

• If your path contains spaces (e.g. C:\Users\John Doe\Skills_MCP_Server or L:\My Innovations\...), write it plainly within JSON strings: "C:\\Users\\John Doe\\Skills_MCP_Server".

• Do not wrap arguments with additional shell quotes inside JSON strings (e.g., use "--skill-root", "C:\\My Skills" instead of "--skill-root", "\"C:\\My Skills\"").

4. Invalid JSON or Misplaced Configuration Keys

• Schema Differences:

  • Windsurf, Claude Desktop, Cursor, and Antigravity use top-level key "mcpServers".

  • Zed uses top-level key "context_servers".

• JSON Syntax Errors: Ensure there are no trailing commas before closing braces (}) or brackets (]), and verify that all keys and strings are enclosed in double quotes.

5. Incorrect Working Directories and Script Paths

• The entry point -m src.server requires Python to resolve the src package directory.

• In Windsurf and Claude Desktop: always set "cwd": "/path/to/Skills_MCP_Server".

• In Zed (which does not have a cwd key): set "env": { "PYTHONPATH": "/path/to/Skills_MCP_Server" } or run pip install -e ..

6. Unsupported Transports, Failed Connections, and Server Startup Errors

• Protocol: Skills MCP Server implements STDIO and Server-Sent Events (SSE). It does not support Streamable HTTP POST RPC.

• SSE URL: When using remote transport in Windsurf or Zed, point to the SSE endpoint: http://localhost:8080/mcp/sse.

• Garbled STDIO Frames: Do not add print statements to stdout in server code; MCP protocol frames require clean standard I/O. All logging in Skills MCP Server is routed to stderr.

7. Reloading Editors and Checking Available MCP Tools

• Windsurf: Click the hammer/refresh icon in the Cascade panel, or restart Windsurf.

• Zed: Save settings.json (auto-reloads), or restart via Command Palette (zed: restart). Ensure worktree trust is granted.

• Verify Tools: When connected, verify that all 10 MCP tools (list_skills, search_skills, get_skill, get_skills, list_profiles, get_profile, resolve_profile, refresh_skills, get_categories, get_skill_stats) appear in your editor's tool list.

Claude Code CLI Setup

Connect Claude Code to Skills MCP Server to give the CLI agent full access to your personal skills library, profiles, and prompts. Both STDIO (local process) and HTTP/SSE (remote/persistent daemon) transports are supported.

Prerequisites

1. Python: Python >= 3.10 is required. Verify your version:

   python3 --version

2. Claude Code CLI: Installed and authenticated:

   npm install -g @anthropic-ai/claude-code
   claude --version

3. Repository Setup: Clone this repository and install its dependencies in a virtual environment:

   git clone https://github.com/rajpreetcodes/Skills_MCP_Server.git
   cd Skills_MCP_Server
   python3 -m venv .venv
   source .venv/bin/activate       # On Windows: .venv\Scripts\activate
   pip install -e .

   (Required dependencies from pyproject.toml: mcp[cli]>=2.2.0, fastapi>=0.141.0, uvicorn>=0.53.0, python-dotenv>=1.1.0, pyyaml>=6.0)

4. Skills Directory: Have a directory containing your skills library (e.g., ~/.claude/skills on macOS/Linux or C:\Users\<username>\.claude\skills on Windows).

5. Configuration (Optional): Set custom options in config.json or via environment variables (SKILL_ROOT, PROFILE_DIR, AUTH_TOKEN, PORT).

Option A: STDIO Transport

When to use STDIO: Recommended for local development when Claude Code runs on the same machine as your skills library. Claude Code launches the server as a child process and communicates directly over standard input/output. No background daemon or open network port is required, and Claude Code manages the server process lifecycle automatically.

1. CLI Registration Command

Run claude mcp add using the --transport stdio flag. The double dash (--) separates Claude Code options from the Python server command:

# From anywhere (replace with your actual paths):
claude mcp add --transport stdio skills \
  -- /path/to/Skills_MCP_Server/.venv/bin/python -m src.server \
  --transport stdio \
  --skill-root /path/to/skills

Windows (PowerShell / CMD):

claude mcp add --transport stdio skills -- C:\path\to\Skills_MCP_Server\.venv\Scripts\python.exe -m src.server --transport stdio --skill-root C:\Users\<username>\.claude\skills

From the repository root:

cd /path/to/Skills_MCP_Server
claude mcp add --transport stdio skills -- python -m src.server --transport stdio --skill-root /path/to/skills

Configuration Details:

• Python executable: Point directly to your virtual environment Python binary (.venv/bin/python or .venv\Scripts\python.exe) so installed dependencies are used.

• Entry point: -m src.server runs the main server entry point.

• Arguments: --transport stdio specifies STDIO mode; --skill-root sets your skills folder (overrides default).

• Scope options: By default, registration applies locally to the current project (~/.claude.json). Add --scope user to make skills available across all projects, or --scope project to save to .mcp.json in the current project root.

2. Manual Configuration File Example

Alternatively, add the server definition directly to ~/.claude.json (user scope) or .mcp.json (project scope):

{
  "mcpServers": {
    "skills": {
      "type": "stdio",
      "command": "/path/to/Skills_MCP_Server/.venv/bin/python",
      "args": [
        "-m",
        "src.server",
        "--transport",
        "stdio",
        "--skill-root",
        "/path/to/skills"
      ],
      "cwd": "/path/to/Skills_MCP_Server"
    }
  }
}

Windows configuration:

{
  "mcpServers": {
    "skills": {
      "type": "stdio",
      "command": "C:\\path\\to\\Skills_MCP_Server\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "src.server",
        "--transport",
        "stdio",
        "--skill-root",
        "C:\\Users\\<username>\\.claude\\skills"
      ],
      "cwd": "C:\\path\\to\\Skills_MCP_Server"
    }
  }
}

Note on cwd: Specifying "cwd" pointing to the Skills_MCP_Server directory ensures Python can resolve the src package.

Option B: HTTP Transport

When to use HTTP: Recommended when running the server on a remote host, inside Docker, or as a persistent daemon accessible simultaneously across multiple MCP clients (such as Claude Code CLI and Tasklet).

Protocol Note: Skills MCP Server implements the Server-Sent Events (SSE) protocol via mcp.server.sse.SseServerTransport. The MCP endpoint is /mcp/sse. It does not support Streamable HTTP.

1. Start the Server

From the repository root, start the server in HTTP mode:

cd /path/to/Skills_MCP_Server
source .venv/bin/activate

# Local development (no authentication)
python -m src.server --transport http --host 0.0.0.0 --port 8080 --skill-root /path/to/skills

If securing the server with a Bearer token (recommended for remote or shared deployments):

export AUTH_TOKEN="your-secure-token-here"
python -m src.server --transport http --host 0.0.0.0 --port 8080 --skill-root /path/to/skills

Verify that the server is up and running:

curl http://localhost:8080/health
# Response: {"status":"healthy","skills":...,"profiles":4,"version":"0.1.0"}

2. Register in Claude Code CLI

Register the SSE endpoint (/mcp/sse) with Claude Code:

# Standard registration (no auth)
claude mcp add --transport sse skills http://localhost:8080/mcp/sse

With Bearer token authentication:

claude mcp add --transport sse skills http://localhost:8080/mcp/sse --header "Authorization: Bearer your-secure-token-here"

(Note: In Claude Code v2.1.265+, --transport http skills http://localhost:8080/mcp/sse also automatically negotiates the SSE transport).

3. Manual Configuration File Example

If using ~/.claude.json or .mcp.json:

{
  "mcpServers": {
    "skills": {
      "type": "sse",
      "url": "http://localhost:8080/mcp/sse"
    }
  }
}

With authentication header:

{
  "mcpServers": {
    "skills": {
      "type": "sse",
      "url": "http://localhost:8080/mcp/sse",
      "headers": {
        "Authorization": "Bearer your-secure-token-here"
      }
    }
  }
}

Verify the Connection

Follow these steps to confirm your connection and diagnose any potential configuration issues.

1. Inspect Server Status via CLI

List registered MCP servers to verify connection status:

claude mcp list

Expected output confirms the server is connected:

skills: ... - ✓ Connected

Inspect detailed server settings:

claude mcp get skills

2. Verify in an Interactive Claude Code Session

Start a Claude Code session:

claude

Inside the session, run the /mcp command:

/mcp

Verify that skills appears active and exposes all 10 MCP tools:

• list_skills — Browse skill catalog with pagination and category filters

• search_skills — Natural language search across skills and tags

• get_skill / get_skills — Retrieve full skill instructions

• list_profiles / get_profile / resolve_profile — Manage and resolve skill bundles

• refresh_skills — Reload skill registry after adding new skills

• get_categories / get_skill_stats — Taxonomy and registry statistics

Test the integration in chat:

Can you search my skills for "python" using the search_skills tool?

3. Troubleshooting Common Issues

To remove and re-register the server at any time:

claude mcp remove skills

MCP Capabilities

Tools

Resources

Prompts

Usage Examples

Agent Workflow: "Design a polished SaaS dashboard"

# 1. Agent searches for relevant skills
results = search_skills("design polished dashboard ui ux")
# → Returns: ui-ux-pro-max, impeccable, choosing-design-styles, design-consultation

# 2. Agent loads top matches
skills = get_skills(["ui-ux-pro-max.ui-ux-pro-max", "impeccable.impeccable", ...])
# → Returns full instructions for each skill, clearly separated

# 3. Agent applies combined expertise to the task

Agent Workflow: "Build a secure production API"

# Use profile for structured workflow
profile = resolve_profile("senior-engineer")
# → Returns: [investigate, diagnose, plan-eng-review, ponytail, tdd, review, cso, ...]

# Or load specific stages
research_skills = resolve_profile("product-builder", stage="research")
impl_skills = resolve_profile("product-builder", stage="implementation")

Using Profiles

# profiles/product-builder.yaml
name: product-builder
stages:
  research:
    - research
    - research-deep
  design:
    - ui-ux-pro-max
    - impeccable
  implementation:
    - ponytail
    - tdd
  validation:
    - qa
    - review

Configuration

Environment Variables

Config File (config.json)

{
  "skill_root": "C:\\Users\\rajpr\\.claude\\skills",
  "profile_dir": "profiles",
  "transport": "stdio",
  "host": "0.0.0.0",
  "port": 8080,
  "log_level": "INFO",
  "auth_token": null
}

Adding Skills

Simply add a new directory under C:\Users\rajpr\.claude\skills\ with a SKILL.md file:

skills/
  my-new-skill/
    SKILL.md          # Required: frontmatter + instructions
    references/       # Optional: supporting files
      guide.md
      data.json

Then call refresh_skills tool or restart the server.

Skill Frontmatter Example:

---
name: my-skill
description: What this skill does
category: ui-ux
version: "1.0.0"
tags: [design, components]
triggers: ["design a button", "create component"]
allowed-tools: [Read, Write, Bash]
license: MIT
---
# My Skill

Instructions here...

Adding Profiles

Create a YAML file in profiles/:

# profiles/my-workflow.yaml
name: my-workflow
description: My custom workflow
skills:
  - skill-one
  - skill-two
profiles:
  - other-profile  # Nested profile
stages:
  phase1:
    - skill-one
  phase2:
    - skill-two

Remote Deployment Architecture

For Tasklet (Cloud)

Since Tasklet runs in the cloud, it cannot access your local Windows filesystem. The remote server must have access to the skill content.

Recommended Approach:

1. Git-backed skills: Push C:\Users\rajpr\.claude\skills to a private Git repo

2. CI/CD sync: On push, CI builds Docker image with skills embedded OR deploys to server that clones the repo

3. Server mounts: Docker volume or persistent disk with skills content

Git Repo (skills) → CI/CD → Docker Image → Cloud Run / K8s / VM
                                                    ↓
                                              Tasklet connects

Docker with Embedded Skills:

# In Dockerfile, copy skills at build time
COPY skills/ /skills/

Or Runtime Sync (for frequent updates):

# In container startup script
git clone https://github.com/you/skills.git /skills
# Then run server with SKILL_ROOT=/skills

Authentication

Always use AUTH_TOKEN for remote deployments:

# Generate secure token
python -c "import secrets; print(secrets.token_urlsafe(32))"

# Set in environment
export AUTH_TOKEN="generated-token-here"

Tasklet connection must include: Authorization: Bearer <token>

Testing

# Run all tests
cd L:\My Innovations\Skills_MCP_Server
pytest tests/ -v

# Run specific test file
pytest tests/test_registry.py -v
pytest tests/test_search.py -v
pytest tests/test_profiles.py -v
pytest tests/test_server.py -v

MCP Inspector Validation

# Install inspector
npm install -g @modelcontextprotocol/inspector

# Test STDIO mode
npx @modelcontextprotocol/inspector python -m src.server --transport stdio

# Test HTTP mode (in separate terminal)
python -m src.server --transport http --port 8080
# Then in inspector: connect to http://localhost:8080/mcp/sse

Troubleshooting

Security Considerations

• Never expose HTTP without auth in production

• Use HTTPS behind reverse proxy (nginx, Caddy, Cloudflare Tunnel)

• Built-in Rate Limiting: In HTTP mode, configurable sliding-window rate limiting (RATE_LIMIT_ENABLED, RATE_LIMIT_PER_MINUTE) protects endpoints against denial-of-service attempts

• Restrict network access to authorized client IPs only

• Read-only skill mount (:ro in Docker)

• No arbitrary code execution: server only reads skill files

Privacy

Skills MCP Server is a local-first engineering tool. It contains zero tracking, zero telemetry, and zero remote analytics. All skill indexing, search queries, and prompt resolutions execute strictly in local process memory on your machine. For complete details, see PRIVACY.md.

Contributing

Contributions are welcome. See CONTRIBUTING.md for development setup, how to add workflow profiles, commit conventions, and the pull request checklist.

License

This project is licensed under the MIT License. See LICENSE for details. Individual skill files retain their respective author licenses in their corresponding directories.