Skill Ninja MCP Server 🥷

![npm version](https://www.npmjs.com/package/skill-ninja-mcp-server) ![License: CC BY-NC-SA 4.0](LICENSE)

日本語版 README

An MCP (Model Context Protocol) server for searching, installing, and managing AI Agent Skills.

Works with MCP-compatible clients like Claude Desktop, Cursor, and VS Code.

Installation

npm install -g skill-ninja-mcp-server

Or run it directly with npx:

npx skill-ninja-mcp-server

Configuration

Claude Desktop

~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "skill-ninja": {
      "command": "npx",
      "args": ["skill-ninja-mcp-server"]
    }
  }
}

VS Code (mcp.json)

%APPDATA%\Code\User\mcp.json:

{
  "servers": {
    "skill-ninja": {
      "command": "npx",
      "args": ["skill-ninja-mcp-server"]
    }
  }
}

Environment Variables

| Variable | Description | Default | | -------------------------------- | --------------------------------------------------------- | ------------------------------------- | | GITHUB_TOKEN | GitHub API token for higher rate limits | none | | SKILL_NINJA_INDEX_DIR | Skill index storage directory | ~/.skill-ninja | | SKILL_NINJA_TRUSTED_WORKSPACES | Trusted workspace roots allowed for read/write operations | auto-detect current project root only | | LANG | Output language, for example ja_JP | system default |

Security

Workspace-mutating tools only operate inside trusted workspace roots.

By default, the server trusts the current working directory only when it looks like a project root.
To allow other locations, set the SKILL_NINJA_TRUSTED_WORKSPACES environment variable to one or more trusted roots separated by your OS path delimiter.
Requests outside trusted roots are rejected before any read, write, or delete occurs.
GitHub API and raw content fetches use a bounded timeout so network failures return control instead of hanging the MCP server indefinitely.

Duplicate Skill Names

Search and recommendation results include the source name for each skill.
If multiple sources publish the same skill name, pass the optional source field to skillNinja_install or skillNinja_localize.
Installed skill listings include the recorded source, and the server refuses to overwrite an installed skill with the same name from a different source.
If a partial skill name matches multiple different skills, the install, localize, and uninstall flows now stop and ask for the exact skill name instead of picking the first match.

Tools

| Tool | Description | | ------------------------ | ---------------------------------------------------------- | | skillNinja_search | Search the local skill index by keyword | | skillNinja_install | Install a skill into a trusted workspace | | skillNinja_uninstall | Remove an installed skill from a trusted workspace | | skillNinja_list | List installed skills in a trusted workspace | | skillNinja_recommend | Recommend skills based on workspace contents | | skillNinja_updateIndex | Refresh the local skill index from registered sources | | skillNinja_webSearch | Search GitHub for repositories containing SKILL.md files | | skillNinja_addSource | Add a GitHub repository as a skill source | | skillNinja_localize | Update localized skill descriptions in the index |

skillNinja_install tries to fetch the original SKILL.md from the source repository. If the source file cannot be resolved or downloaded, it installs a minimal file generated from the local index and reports that fallback in the result.

Usage Examples

"Find skills for Azure work"
  -> skillNinja_search

"Install the webapp-testing skill from GitHub Awesome Copilot"
  -> skillNinja_install with skillName="webapp-testing" and source="github-awesome-copilot"

"Install test"
  -> refine to the exact skill name first, for example "test-driven-development"

"Search GitHub for MCP skills"
  -> skillNinja_webSearch

Development

git clone https://github.com/aktsmm/skill-ninja-mcp-server
cd skill-ninja-mcp-server
npm install
npm test
npm run release:verify

License

CC BY-NC-SA 4.0 — see LICENSE.

skill-ninja-mcp-server