@innlabkz/flux-mcp-server

MCP (Model Context Protocol) server for Flux. Plug it into Claude Desktop or Claude Code and Claude can read your projects/tasks/comments/audit-log/GitHub-commits and create/update tasks on your behalf — through normal chat.

Thin wrapper over the Flux REST API. Authenticates with a single long-lived Personal Access Token (PAT) — no refresh-token dance, no sudden 401s after 15 minutes.

Quick install

You don't need to clone anything. npx handles the rest.

1. Get a Personal Access Token

Log in to flux.innlab.kz and open:

https://flux.innlab.kz/settings/mcp-token

Click "+ Generate", name the token (e.g. MacBook MCP), then click "📋 Copy JSON". You get a fully-prefilled snippet ready to paste.

⚠️ The token is shown once. If you lose it, generate a new one.

2. Open Claude config

Claude Desktop (macOS):

~/Library/Application Support/Claude/claude_desktop_config.json

Claude Desktop (Windows):

%APPDATA%\Claude\claude_desktop_config.json

Claude Code:

~/.claude.json

3. Paste the snippet

If the file is empty, paste as-is. If it already has mcpServers, merge — add only the "flux": { … } entry inside the existing object:

{
  "mcpServers": {
    "flux": {
      "command": "npx",
      "args": ["-y", "@innlabkz/flux-mcp-server@latest"],
      "env": {
        "FLUX_API_URL": "https://flux.oqai.org",
        "FLUX_API_TOKEN": "flux_pat_…"
      }
    }
  }
}

4. Restart Claude

Desktop: quit completely (Cmd+Q on macOS / right-click tray icon → Quit on Windows), then reopen. Just closing the window is not enough.

Code: new chat sessions pick it up automatically. Run claude mcp list to verify.

Done. Ask Claude "покажи мои проекты в Flux" / "show my Flux projects" — it should call flux_list_projects.

Claude Code one-liner (alternative)

Skip the config-file edit. Real syntax: claude mcp add [opts] <name> <command> [args...] — env vars via -e, scope via -s, everything after -- is the spawned command.

claude mcp add flux -s user \
  -e FLUX_API_URL=https://flux.oqai.org \
  -e FLUX_API_TOKEN=flux_pat_… \
  -- npx -y @innlabkz/flux-mcp-server@latest

Scopes:

• -s user (recommended) — global, visible in every project
• -s local (default) — current directory only
• -s project — written to .mcp.json in the project (committable)

Verify with claude mcp list and claude mcp get flux.

⚠️ Watch the line continuations. In zsh, a \ followed by a trailing space breaks the continuation and zsh runs each line as a separate command — you end up with a half-registered server with an empty command. Either type the whole thing on one line, or make sure there's nothing after the \.

What it exposes (42 tools)

Organizations

| Tool | Action | |---|---| | flux_list_organizations | List orgs the user belongs to |

Projects

| Tool | Action | |---|---| | flux_list_projects | List projects (filter by org / status) | | flux_get_project | Fetch a project by id | | flux_create_project | Create a new project | | flux_list_repositories | List GitHub repos linked to a project | | flux_add_repository | Link a GitHub repo to a project | | flux_remove_repository | Unlink a repo from a project |

Tasks

| Tool | Action | |---|---| | flux_list_tasks | List tasks in a project (cursor-paginated) | | flux_get_task | Fetch a task by id | | flux_get_task_by_key | Resolve a task by human key (PRJ-12) | | flux_create_task | Create a new task (supports parentTaskId for subtasks) | | flux_update_task | Partial task update | | flux_set_task_status | Convenience: change status via key or id | | flux_set_task_priority | Convenience: change priority via key or id | | flux_delete_task | Delete a task | | flux_list_assignable_members | Members you can assign to a task |

Subtasks & checklist

| Tool | Action | |---|---| | flux_list_subtasks | List child tasks of a parent task | | flux_list_checklist | List checklist items on a task (each item has itemKey like IF-01_01 + blockers[]) | | flux_add_checklist_item | Add a checklist item (auto-assigned itemKey) | | flux_update_checklist_item | Toggle done / rename a checklist item. Returns 409 if item is blocked by an open dependency. | | flux_delete_checklist_item | Remove a checklist item |

Checklist blockers (cross-task dependencies)

| Tool | Action | |---|---| | flux_link_checklist_blocker | Link two checklist items so the first cannot close until the second is done (same project) | | flux_unlink_checklist_blocker | Remove a blocker edge between two checklist items | | flux_search_checklist_items | Search checklist items across a project by item key or text |

Comments & audit

| Tool | Action | |---|---| | flux_list_task_comments | Comments on a task | | flux_add_task_comment | Post a comment to a task | | flux_list_task_audit_log | Who changed what on a task (by key or id) |

Sprints

| Tool | Action | |---|---| | flux_list_sprints | List sprints in a project | | flux_get_sprint | Fetch a sprint by id | | flux_create_sprint | Create a sprint | | flux_update_sprint | Update sprint fields / state | | flux_delete_sprint | Delete a sprint | | flux_list_sprint_tasks | Tasks assigned to a sprint | | flux_list_backlog | Project tasks not in any sprint | | flux_assign_task_to_sprint | Move a task into a sprint | | flux_unassign_task_from_sprint | Remove a task from a sprint |

Tags

| Tool | Action | |---|---| | flux_list_tags | List tags in a project | | flux_create_tag | Create a tag |

GitHub

| Tool | Action | |---|---| | flux_github_status | Check GitHub integration status for the user | | flux_list_project_commits | Recent GitHub commits for a linked project repo (live API) | | flux_list_task_commits | Commits whose message references a task key (default branch) | | flux_list_task_branch_commits | Commits on a feature branch matching the task key (unmerged work) |

All tools validate their inputs with zod schemas — Claude can't pass invalid UUIDs or enums.

Environment variables

| Var | Required | Description | |---|---|---| | FLUX_API_URL | yes | Flux backend URL (e.g. https://flux.oqai.org). No trailing /api/v1 — server prepends path itself. | | FLUX_API_TOKEN | yes | Personal Access Token (flux_pat_*). Issue at /settings/mcp-token. Lifetime: 1 year, no rotation. | | FLUX_ACCESS_TOKEN | legacy | Deprecated. Short-lived JWT (15 min) — works once, then expires. Use FLUX_API_TOKEN instead. |

Local backend / dev

If you run Flux locally (./mvnw spring-boot:run):

{
  "env": {
    "FLUX_API_URL": "http://localhost:7071",
    "FLUX_API_TOKEN": "flux_pat_…"
  }
}

Updating

npx -y @innlabkz/flux-mcp-server@latest always pulls the latest published version on Claude restart. Nothing to do.

To force-refresh the cache:

rm -rf ~/.npm/_npx

Then restart Claude.

Troubleshooting

Server doesn't appear in Claude

1. Make sure JSON is valid. Paste into jsonlint.com if unsure.
2. Restart Claude fully (not just window close).
3. Check logs:
   • macOS: ~/Library/Logs/Claude/mcp*.log
   • Windows: %APPDATA%\Claude\logs\mcp*.log

Flux 401 Unauthorized

Token expired, revoked, or invalid. Go to /settings/mcp-token, generate a new PAT, replace FLUX_API_TOKEN, restart Claude.

If you're still on the legacy FLUX_ACCESS_TOKEN (JWT) — it expires after 15 min. Migrate to a PAT.

Flux 403 Forbidden

You don't own this project/task. MCP runs under your user — you only see what you'd see via the web UI.

Empty results

Same as above — server uses your own token, no service-account magic. If REST returns empty, so does MCP.

Security

• FLUX_API_TOKEN lives only in the spawned Node process memory. The server never writes it to disk, never logs it, never sends it anywhere except to your FLUX_API_URL.
• Backend stores only SHA-256 hash of the token — a database leak can't be turned back into auth credentials.
• Revoke tokens you no longer need at /settings/mcp-token (Revoke button).
• Your Claude config file is local but stored in plain JSON. Don't commit it to git. Treat it like a .env.
• The server doesn't proxy the in-app AI chat. It's a tool surface for the host LLM (Claude Desktop / Code), independent of Flux's internal AI assistant.

Building from source

Only needed if you're contributing or want a frozen local version.

git clone https://github.com/bekzatsk/innlab-flux.git
cd innlab-flux/tools/mcp-server
npm install
npm run build

Then point Claude at dist/index.js:

{
  "mcpServers": {
    "flux": {
      "command": "node",
      "args": ["/abs/path/to/innlab-flux/tools/mcp-server/dist/index.js"],
      "env": { "FLUX_API_URL": "…", "FLUX_API_TOKEN": "flux_pat_…" }
    }
  }
}

Source repo is private — clone access required.

Links

• Full guide: MCP_INSTRUCTION.md (in the source repo)
• Web UI: https://flux.innlab.kz
• Token page: https://flux.innlab.kz/settings/mcp-token
• MCP protocol spec: https://modelcontextprotocol.io

License

UNLICENSED — internal Innlab tool. Not for redistribution.