@rui.branco/claude-commands-mcp

@rui.branco/claude-commands-mcp

MCP server that serves skill/slash-command definitions from a private git repository. Each skill is registered as its own MCP tool with trigger keywords — the host AI client discovers and calls them on matching user input.

Primarily designed for Claude Code (the "skills" / slash-command model maps directly onto Claude's tool-discovery loop), but the underlying transport is plain MCP — any MCP-compatible client (Codex CLI, Google's Antigravity / Gemini, Cursor, Windsurf, Zed, Cline, Continue, etc.) can mount this server and call the tools. How effective the trigger-keyword routing is in each client depends on how that client decides to invoke MCP tools.

Setup

Install globally:

npm install -g @rui.branco/claude-commands-mcp

Register with your MCP client. Pick the snippet for your client (substitute your own private repo URL):

Claude Code:

claude mcp add --transport stdio claude-commands -e COMMANDS_REPO=https://github.com/your-user/your-private-repo.git -- claude-commands-mcp

Codex CLI: add to ~/.codex/config.toml:

[mcp_servers.claude-commands]
command = "claude-commands-mcp"
env = { COMMANDS_REPO = "https://github.com/your-user/your-private-repo.git" }

Google Antigravity / Gemini CLI: add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "claude-commands": {
      "command": "claude-commands-mcp",
      "env": { "COMMANDS_REPO": "https://github.com/your-user/your-private-repo.git" }
    }
  }
}

Cursor, Windsurf, Zed, Cline, Continue, etc.: add the same command / env pair to whatever JSON config that client uses for MCP servers — the shape is standard across clients.

COMMANDS_REPO (required) — URL of the git repo containing your skills and config. Private repos work as long as git credentials are configured locally.

Restart your AI client and check its MCP status (e.g. /mcp in Claude Code, mcp in Codex CLI, or the equivalent panel in your client) to activate.

How it works

On startup the server clones COMMANDS_REPO to ~/.cache/claude-commands-mcp/ (subsequent starts pull in the background without blocking). It reads commands.yaml and registers each skill as a dedicated MCP tool with trigger keywords in the description. The host AI client discovers and routes to these tools using its own tool-discovery mechanism (in Claude Code, that's ToolSearch).

Skill tools

Each skill defined in commands.yaml becomes its own MCP tool. For example, a skill named my-skill becomes mcp__claude-commands__my_skill. When the user's message matches the trigger keywords, the host AI client calls the tool and receives the full instructions.

Utility tools

get_skill(name)

Manual skill lookup by name. Use this to access any .md file in the commands/ directory, including data files not registered as tools.

save_file(path, content, message?)

Saves or updates a file in the commands/ directory, commits, and pushes to git.

save_file("reports/2026-02-07.md", "# Daily Report\n\n- Deployed v2.1...", "update: daily report")

list_skills()

Lists all available skills discovered in the commands/ directory.

refresh()

Pulls latest changes from the git repository.

Repository structure

Your private git repo should contain:

commands.yaml          # Routing rules — each skill becomes an MCP tool
commands/
└── *.md               # Skill definitions (nested folders supported)

commands.yaml format

skills:
  - skill: my-skill
    category: General
    when: |
      User says: "do something", "run my skill", etc.

  - skill: folder/nested
    category: General
    when: |
      User says: "nested thing", etc.

general_rules:
  - Some general instruction for the AI.

Each entry in skills registers an MCP tool. The when field becomes the tool description so the AI client knows when to call it.

Skill files

Each .md file in commands/ is a skill. Only skills listed in commands.yaml get their own tool. Other .md files are accessible via get_skill().

• commands/my-skill.md + yaml entry → tool mcp__claude-commands__my_skill
• commands/folder/nested.md + yaml entry → tool mcp__claude-commands__folder_nested

Persisting data with save_file

Skills can produce data that needs to persist across sessions. The save_file tool writes files to the commands/ directory, commits, and pushes — so everything stays in git.

Typical use cases:

• Tracking files — a skill that logs activity can append entries over time
• Generated configs — a skill that produces configuration can save it for future reference
• Accumulated data — any skill that builds up state across sessions

Updating

npm update -g @rui.branco/claude-commands-mcp

Restart your AI client to pick up the new version.