Oss Autopilot

@oss-autopilot/mcp

MCP server for OSS Autopilot — exposes PR tracking, issue discovery, and contribution management as MCP tools for any MCP-compatible client.

[npm] [Node] [License]

What It Provides

Supports stdio (default) and Streamable HTTP transports.

Prerequisites

• Node.js 22+
• GitHub CLI authenticated (gh auth login)

Quick Start

# 1. Add the server to your MCP client (see config examples below)
# 2. From your MCP client, call the `init` tool once with your GitHub username#    (this writes ~/.oss-autopilot/state.json).
# 3. Use the other tools — e.g. `daily` to check your PRs, `search` to find issues.

Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{  "mcpServers": {    "oss-autopilot": {      "command": "npx",      "args": ["@oss-autopilot/mcp@latest"]    }  }}

Cursor

Add to .cursor/mcp.json in your project or global config:

{  "mcpServers": {    "oss-autopilot": {      "command": "npx",      "args": ["@oss-autopilot/mcp@latest"]    }  }}

Codex CLI

codex mcp add oss -- npx @oss-autopilot/mcp@latest

Windsurf

Add to your Windsurf MCP config:

{  "mcpServers": {    "oss-autopilot": {      "command": "npx",      "args": ["@oss-autopilot/mcp@latest"]    }  }}

Streamable HTTP (any client)

Run the server in HTTP mode instead of stdio:

npx @oss-autopilot/mcp@latest --http --port 3001

The server listens at http://127.0.0.1:3001/mcp and accepts POST requests.

Authentication

HTTP mode requires a bearer token on every request (stdio mode does not — it inherits the parent process identity). On first --http startup, the server generates a random 32-byte token and writes it to ~/.oss-autopilot/mcp.token with 0600 permissions. The path and "newly generated" marker are logged to stderr at startup.

Every HTTP client must send:

Authorization: Bearer <contents of ~/.oss-autopilot/mcp.token>

Requests without a valid Authorization header return 401. The Bearer scheme is case-insensitive per RFC 7235; the token value itself is compared byte-for-byte in constant time. Requests with a non-loopback Host header return 403 (DNS-rebinding defense). Requests must declare a numeric Content-Length ≤ 1 MiB — missing, non-numeric, or oversize Content-Length values return 413.

The token persists across restarts. To rotate, delete the file and restart — a new token will be generated. To relocate the token (e.g. for multi-user or CI setups), set OSS_AUTOPILOT_MCP_TOKEN_PATH to the desired absolute path before starting the server.

Tools Reference

Resources Reference

Prompts Reference

Multiple Machines

With Gist persistence, every client that runs oss-autopilot (the plugin on each machine, and every MCP server process) reads and writes the same state. Since core 3.35.0, a client keeps state fields it does not recognise instead of dropping them, and warns when the state was written by a different release. Clients on older releases still drop newer fields when they save, so update every machine after a release and restart running MCP servers, which keep the version they started with.

Programmatic Usage

The server can also be imported and used as a library:

import { createServer } from '@oss-autopilot/mcp';
const server = createServer();// Connect to your own transport

More Information

See the main repository README for the full documentation, including the Claude Code plugin, CLI usage, dashboard, and contributing guide.

License

MIT