codex-skills-mcp

Codex Skills MCP is a production-oriented Model Context Protocol server and an installable Codex/ChatGPT desktop plugin for a continuously updated expert-skill library. It indexes a lightweight catalog, searches locally, downloads selected skills on demand, verifies every file, and keeps the working set auditable on disk.

Available as: GitHub-distributed Codex desktop plugin · standalone stdio MCP server · self-hosted Streamable HTTP MCP server.

Why Codex Skills MCP

Related MCP server: studiox-skills-mcp

Quick Start

Codex desktop plugin

Add this repository as a Codex marketplace once:

codex plugin marketplace add Zhan-ZhangZ/codex-skills-mcp --ref main

Then install it from the Codex Plugins directory, or from the CLI:

codex plugin add codex-skills@codex-skills-marketplace

Plugin users do not need Node.js, npm or npx. The plugin launcher starts the bundled MCP server with the runtime supplied by the Codex desktop app. Start a new chat after installation.

See GitHub plugin marketplace for updates, version pinning, runtime selection and troubleshooting.

Standalone MCP server

Standalone stdio and self-hosted deployments require Node.js 22 or newer:

npx -y codex-skills-mcp@beta

The current source release is 1.6.2. The beta npm dist-tag remains the standalone channel for the current feature line.

Codex CLI

codex mcp add codex-skills -- npx -y codex-skills-mcp@beta

Or add this to ~/.codex/config.toml:

[mcp_servers.codex-skills]
command = "npx"
args = ["-y", "codex-skills-mcp@beta"]

Claude Desktop

{
  "mcpServers": {
    "codex-skills": {
      "command": "npx",
      "args": ["-y", "codex-skills-mcp@beta"]
    }
  }
}

Cursor

Create .cursor/mcp.json in the project:

{
  "mcpServers": {
    "codex-skills": {
      "command": "npx",
      "args": ["-y", "codex-skills-mcp@beta"]
    }
  }
}

More client and self-hosting setups are in Installation.

How It Works

flowchart LR
    A["MCP client"] --> B["Codex Skills MCP"]
    B --> C["Local manifest + BM25 index"]
    C --> D["Tool result: candidate skills"]
    D --> E["read_skill: selected skill only"]
    E --> F["Verified local cache"]
    F --> G["Agent executes SKILL.md"]
    F --> H["MCP App / resources"]

The server never downloads the entire library at startup. It loads a compact manifest, builds a keyword/task index locally, then materializes complete skill directories only after selection. See Architecture and Agent protocol.

The Codex plugin uses the same stdio MCP implementation. Only installation and runtime discovery change: Codex launches a compact cross-platform launcher instead of resolving npx and a user-installed Node.js binary.

The screenshot uses the deterministic preview host. Live skill, domain and usage counts come from the current manifest and local usage history.

Tool Surface

Core tools

All standard MCP clients receive these 8 tools:

Host compatibility

中文兼容提示： 可视技能库和技能托盘（skills.tray）是 MCP Apps 界面，不是标准 MCP 能力。安装本项目本地插件时，它们只会在支持 MCP Apps 的 ChatGPT 桌面端或 Codex 桌面端出现。Codex CLI、Claude Desktop、Cursor、 Windsurf 等客户端仍可使用 8 个核心工具和 skill:// 资源，但不会显示技能托盘。 本地插件在 ChatGPT 中也只应在本地执行线程里使用，@ 提及不会出现在云端线程。

The bundled local plugin is Desktop only. Its UI library, skills.tray skill tray, attachment handoff, @ mentions and native settings panel require a ChatGPT/Codex desktop host that supports MCP Apps and OpenAI MCP extensions. The local plugin can only be installed from the ChatGPT desktop app, and the manifest is marked with requires_local_executor.

Standard MCP clients still receive the complete agent workflow through the 8 core tools and skill:// resources; they do not display the visual skill tray.

MCP Apps and host extensions

ChatGPT/Codex MCP Apps hosts additionally receive the interactive library, settings, mentions and app-facing tools. This includes:

• skills.library, skills.tray, skills.browse and skills.query;

• shared search history and progress tools;

• inline image preview and per-skill cache removal;

• settings.read, settings.update and refresh_skills_list;

• search_mentions and the skill://{name} resource family.

Use --tool-profile core|full|auto to override host detection. The complete reference is in Tools and Host extensions.

Configuration

The defaults work without a config file. Common options:

--cache-dir <path>             Cache location
--skills-dir <path>            Use a local skill library
--http                         Start Streamable HTTP transport
--host <addr>                  HTTP bind address
--port <port>                  HTTP port
--tool-profile <mode>          auto | core | full
--manifest-ttl <seconds>       Manifest refresh age
--manifest-poll <seconds>      Background freshness poll
--download-concurrency <n>     Parallel skill file downloads
--no-official-mirror           Disable the official CN endpoint
--no-hedge                     Race all endpoints immediately

Full flags, environment variables and persisted settings are documented in Configuration.

Security and Privacy

• HTTP mode binds to 127.0.0.1 by default and validates Host/Origin allowlists.

• GitHub credentials are sent only to GitHub endpoints, never to mirrors.

• Skill paths are checked for traversal and symlink escapes.

• Downloaded files are validated before they are accepted as cache content.

• App Markdown is sanitized, and external links open with noopener noreferrer.

• Anonymous usage counting is enabled by default. On upgrade it uploads one per-skill cumulative backfill, then daily successful-call increments. It never uploads prompts, paths or task content. Users can disable uploads in plugin settings without affecting local usage.

See SECURITY.md for vulnerability reporting and the threat model, and PRIVACY.md for telemetry details and opt-out behavior.

Commercial Use

Personal, educational, open-source and internal business use is free. Commercial sale, paid deployment/support, paid hosting, or bundling with a paid product requires the official logo, non-original-source notice and source link defined by the license.

非原创：本项目基于 codex-skills-mcp（合塑研工）二次开发，由 [销售方名称] 独立提供，非原作者官方发行版。

Read Commercial licensing, the controlling LICENSE, and the ready-to-use brand assets. This is a source-available license, not a standard OSI-approved license.

Documentation

Development

npm ci
npm test
npm run build:plugin
npm run check:plugin
npm run check:package

The default suite is offline and covers search, cache validation, hedging, HTTP safety, MCP Apps, extension registration and real stdio flows. CI runs on Node.js 22 and 24 and exercises the plugin launcher on macOS, Windows and Linux.

Contributions are welcome. Read CONTRIBUTING.md before opening a pull request. Use Support for operational questions.

Project Layout

src/         MCP server, search, loader, transport and tools
app-src/     MCP App frontend source
assets/      Built app asset
plugin/      Codex plugin distribution
.agents/     GitHub marketplace catalog
brand/       Official logo and commercial attribution kit
docs/        User and maintainer documentation
examples/    Ready-to-copy MCP client configurations
scripts/     Build, verification and benchmark utilities
test/        Offline regression suites

License

Codex Skills MCP Commercial Attribution License 1.0, with an unofficial Chinese reference. Third-party content remains under its own terms; see NOTICE.

Codex Skills MCP is an independent project and is not an official product of OpenAI, Anthropic, Cursor or any other MCP host vendor.