@grantfox-oss/mcp

MCP server that exposes GrantFox tools to Claude Code (and any other MCP client). Designed for maintainers - list your projects, manage issues, attach campaigns, assign contributors, all from your editor.

Quick start (for users)

# 1. Register the MCP server with Claude Code (requires `claude` on PATH)
npx -y @grantfox-oss/mcp setup claude --write

# 2. Generate a Claude Code token in the maintainer app:
#    Settings → Personal Access Tokens → Generate Claude Code Token
#    Select the project(s) Claude can publish issues for, then copy the gfox_... value.

# 3. Sign in locally
npx -y @grantfox-oss/mcp auth login

That's it. setup claude --write runs claude mcp add-json grantfox ... -s user (user scope, all projects). Without --write, the same command is printed for you to run manually. Restart Claude Code and run /mcp to confirm grantfox is connected.

The token is stored locally at ~/.grantfox/config.json with mode 0600. GrantFox stores only a hash of personal access tokens and cannot show them again.

By default the MCP uses https://api.grantfox.xyz/api. To point at another backend for testing, pass the same API URL to setup and login:

npx -y @grantfox-oss/mcp setup claude --write --api-url https://staging-api.example.com/api
npx -y @grantfox-oss/mcp auth login --api-url https://staging-api.example.com/api

Tools

| Tool | What it does | |---|---| | grantfox_get_me | Returns the authenticated user. Quick auth check. | | grantfox_list_my_projects | Projects where you are an active maintainer. | | grantfox_get_project | Full project details, including its repositories. | | grantfox_list_issues | Issues for a project, filterable by state, labels, campaign, etc. | | grantfox_get_issue | Full issue detail + contributor applications. | | grantfox_prepare_issue | Prepare an issue draft for maintainer review. Does not publish. | | grantfox_publish_issue | Publish a reviewed draft using draft_id and approved_hash. | | grantfox_attach_issue_to_campaign | Attach (or detach with null) an issue to a campaign. MAINTAINER. | | grantfox_assign_contributor | Assign a GitHub user to an issue. MAINTAINER. | | grantfox_unassign_contributor | Unassign a GitHub user from an issue. MAINTAINER. | | grantfox_list_campaigns | List GrantFox campaigns. | | grantfox_list_notifications | Your notifications. | | grantfox_list_my_tokens | Your active PATs (no plaintext). Audit only - manage from the UI. |

Auth commands

grantfox-mcp auth login [--token gfox_...] [--api-url <url>]  # save token
grantfox-mcp auth status [--api-url <url>]                    # verify token
grantfox-mcp auth logout                                      # clear token
grantfox-mcp setup claude [--write] [--api-url <url>]         # register MCP via claude CLI

setup claude --write registers the server via claude mcp add-json ... -s user (user scope, all projects) and requires the claude CLI on PATH. Without --write, it prints that command for manual copy-paste.

Token file: ~/.grantfox/config.json (mode 0600). The selected API URL is stored with the token so serve can use the same backend later.

How to verify the server is working

A scripted proof runs 12 checks (build, MCP handshake, schema validation, friendly errors, auth state, live API calls, optional create-issue smoke test):

cd apps/mcp-server

npm run proof:offline  # build + offline MCP checks
npm run proof:live     # live API checks with your local token

npm run proof:live --project <uuid> lets you target a specific project.

Local dev

Point at a local core-api:

GRANTFOX_API_URL=http://localhost:3000 node dist/index.js serve

What's NOT included (and why)

• Project create/delete - heavy approval flow, doesn't fit one-shot tool calls.
• Escrow operations - involves money; deserves explicit UI confirmation.
• Application accept/reject - depends on human judgment; do it from the UI.
• Token create/delete - security boundary belongs in the web UI, not a tool. The MCP can list its own tokens for auditing.