Okffs

What the okffs MCP server does

The okffs MCP server gives Claude Code an MCP interface for coordinating GitHub-based development work. It can turn a task description into issues and matching branches, preserve relationships between issues, and connect those issues to pull requests. An Epic is treated differently: it does not receive its own branch or draft pull request, because implementation is expected to land through child issues.

The workflow covers planning, implementation, review, and release preparation. You can list open work as a priority-ordered tree, inspect or edit issue details, move issues between supported project columns, and set board fields or native issue types. Destructive operations such as deleting an issue or branch require explicit confirmation.

How it works

Claude Code calls the server's tools over MCP. Planning tools accept a free-text description or task list and can create multiple issues, branches, labels, assignments, milestones, field values, and relationships. When enabled, issue creation can also open draft pull requests.

For implementation work, the server can stage tracked changes, create a commit, push it, and add a progress comment. Pull request creation generates the title and body, includes a closing reference to the issue, pushes the branch, and comments on the issue. Review tools retrieve inline threads, post replies, and optionally resolve threads when the corresponding setting is enabled.

Merge and promotion actions have separate opt-in controls and safety checks. Base-branch merging requires a green, review-resolved pull request and does not target the configured protected branch. Release preparation updates the version and changelog on a release branch, then opens a pull request without tagging or publishing.

Setup and configuration

Install or run the package through npx and register it as a stdio MCP server in the project's .mcp.json:

{
  "mcpServers": {
    "okffs": {
      "command": "npx",
      "args": ["@neturely/okffs@latest"]
    }
  }
}

From the repository root, npx @neturely/okffs setup launches a wizard for authentication, repository selection, and optional features. It writes the okffs section of .env and runs a GitHub check. The setup flow can also be started from Claude Code with /okffs:setup; its configuration tool preserves unrelated variables and comments. Existing gh authentication inside the repository can be used without additional configuration.

Optional settings control inference, project synchronization, automatic pull requests, merge behavior, review-thread resolution, documentation updates, release tagging, and multisite release handling. Project-column and board-field tools require project support to be enabled.

Tools and capabilities

The available capabilities include:

• Create one issue and branch, many issues from a list, or a complete planned breakdown.
• List and inspect issues, edit core fields, add comments, close work, and link issues as parent, blocking, or blocked by relationships.
• Commit and push changes, create issue pull requests, apply issue-less fixes to the base branch, and promote the base branch toward a protected branch.
• Read pull request review threads, reply to comments, and optionally resolve them.
• Prepare version and changelog changes in a release pull request.
• Update project status, set priority or effort, and assign native issue types.
• Delete an issue with its branch or delete a branch with its issue after confirmation.

The okffs MCP server also includes a configuration tool intended mainly for the setup prompt rather than direct conversational use.

Limitations and notes

The server operates around GitHub issues, branches, pull requests, and optional GitHub Projects features. It does not publish releases as part of prepare_release; that tool prepares and opens the release pull request only. Empty tracking pull requests require allow_empty: true and create an initial empty commit so the branch diverges.

Untracked files are excluded from commits unless include_untracked: true is supplied, and secret-looking files are refused. Issue labels and assignees supplied to update_issue replace the existing sets rather than appending to them. Status changes use update_project_status, while priority, effort, and type use set_issue_fields.

Automatic merging is disabled unless explicitly enabled and remains gated by branch, check, mergeability, and review conditions. Destructive issue and branch operations require a second confirmed call.