How do I use hacknplan-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@hacknplan-mcp list my projects" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

hacknplan-mcp

by mtuska

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

@mtuska/hacknplan-mcp

A Model Context Protocol (MCP) server for the HacknPlan project-management API, built for use with Claude. It exposes HacknPlan projects, boards, work items, sub-tasks, dependencies, time logs, the design model, and metrics as MCP tools — plus a cross-project portfolio dashboard and a deadline schedule view that HacknPlan has no native equivalent for.

Pure TypeScript/Node — runs over npx, no Python or other runtime required.

Quick start

npx @mtuska/hacknplan-mcp install

The installer will:

Ask where to register the server with Claude — global (all your projects), project (this repo, shared via .mcp.json), or local (this repo, private to you).
Prompt for your HacknPlan API key (input is hidden) and store it in the chosen Claude MCP config.
Install the bundled hacknplan Claude skill into the matching skills directory (global → ~/.claude/skills, project/local → ./.claude/skills).

Then ask Claude to run the hacknplan_whoami tool to confirm the key works. (Restart Claude / reload the window first if it was already running.)

The bundled skill (auto-updating)

install drops a hacknplan skill that teaches Claude how to drive these tools (id-resolution, feature breakdown, destructive-confirm rules, the portfolio / schedule / standup views). It's part of the npm package, so on every later server launch — which Claude runs via npx -y @mtuska/hacknplan-mcp (always the latest) — the server re-syncs the skill if the package version changed, keeping it current with no action from you.

The refresh only touches a skill copy this package installed (tracked by a .installed-by.json marker), so your own edits to other skills are never affected. Pass --skip-skill to register the MCP server without the skill.

Updating from a version before the skill existed (≤ 0.2.0): the auto-sync is update-only — it refreshes a skill it previously installed, but does not create one. If you installed the MCP server before the skill shipped (v0.3.0), re-run install once to add it:
npx -y @mtuska/hacknplan-mcp install --global
After that, every later upgrade auto-updates it on the next server launch.

Getting an API key

HacknPlan → your avatar → Settings → API → Create. Tick the scopes you need.

Related MCP server: HAOps MCP Server

Install options

npx @mtuska/hacknplan-mcp install [options]

  -g, --global        Register for all projects (private, in ~/.claude.json). Default.
  -p, --project       Register for this repo only, shared via ./.mcp.json.
      --local         Register for this repo only, private to you.
      --api-key KEY   Provide the key non-interactively (else prompted / $HACKNPLAN_API_KEY).
      --name NAME     Server name to register (default: "hacknplan").
      --skip-skill    Register the MCP server only; don't install the Claude skill.
  -y, --yes           Non-interactive; use defaults and fail if the key is missing.

Non-interactive example (e.g. CI / dotfiles):

HACKNPLAN_API_KEY=hp_xxx npx @mtuska/hacknplan-mcp install --global -y

Project scope & secrets: --project writes the key into ./.mcp.json, which is typically committed. For shared repos prefer --global, or add .mcp.json to .gitignore.

The installer uses the official claude mcp add-json command when the Claude Code CLI is available, and otherwise writes the MCP config file directly.

Manual configuration

If you'd rather not use the installer, add this to your Claude MCP config (~/.claude.json for global, or a project .mcp.json):

{
  "mcpServers": {
    "hacknplan": {
      "command": "npx",
      "args": ["-y", "@mtuska/hacknplan-mcp"],
      "env": { "HACKNPLAN_API_KEY": "hp_your_key_here" }
    }
  }
}

Environment variables

Variable	Required	Purpose
`HACKNPLAN_API_KEY`	yes	`Authorization: ApiKey <key>` for the HacknPlan API.
`HACKNPLAN_GROUPS`	no	JSON map of group label → project names, for the portfolio grouping.

HACKNPLAN_GROUPS='{"Products":["Website","Mobile App"],"Ops":["Infra"]}'

Tools

75 tools across the HacknPlan surface. Highlights:

Read/introspect — hacknplan_whoami, list_projects, get_project, list_work_items (rich server-side filters), get_work_item, list_stages/categories/tags/boards/milestones/importance_levels.
Search & focus — find_work_items (free-text + facet search to resolve a task by name into its id) and my_work (what's assigned to you, per-project or across all).
Work items — create_work_item (with story→task parent_id, assignees, dependencies, checklists), update_work_item (re-stage / re-prioritize / recategorize / re-estimate / reassign / move board·milestone), plan_feature (create a user story + child tasks + checklists in one call), delete_work_item, add_comment, sub-tasks, tags, user assignment.
Planning — create_project/update_project/delete_project, stages, categories, tags, importance levels, boards (create_board/update_board/close_board/reopen_board), milestones (create_milestone/update_milestone/delete_milestone), dependencies.
Lifecycle — non-destructive archive/release via close_project/reopen_project and close_milestone/reopen_milestone.
Activity & metrics — recent_activity (the "what changed this week" / standup feed), log_work, list_work_logs, get_project_metrics, get_milestone_metrics, get_board_metrics (sprint burndown).
Design model — *_design_element/*_design_element_type, plus get_design_element_metrics and design-element comments (list/add_design_element_comment) for the feature/knowledge tree.
Portfolio (cross-project) — portfolio_overview (completion %, urgent / blocked / due-soon / overdue across all projects) and schedule_overview (a deadline countdown bucketed by horizon).

Destructive tools (delete_*, remove_dependency) require confirm=true.

Development

npm install
npm run build        # tsc -> dist/
npm run typecheck
npm run dev          # run the CLI from source via tsx
node dist/cli.js serve   # run the MCP server over stdio

Publishing

Releases are tag-driven via .github/workflows/release.yml. Pushing a vX.Y.Z tag validates that it matches package.json, publishes to npm, and creates the GitHub release:

npm version patch        # bumps package.json (CLI + server read it at runtime)
git push --follow-tags

Publishing uses npm Trusted Publishing (OIDC) with provenance — no NPM_TOKEN secret. One-time maintainer setup:

Publish v0.1.0 once manually (npm publish --access public) to claim the @mtuska/hacknplan-mcp name.
On npmjs.com → the package → Trusted Publishers, add this repo (mtuska/hacknplan-mcp) and the workflow filename (release.yml).

After that, every tag-driven release publishes with provenance and no long-lived token. Users can verify with npm audit signatures.

License

MIT © Montana Tuska

Available Tools

75 tools

add_commentA

Add a comment to a work item (markdown supported, max 5000 chars).

Inputs: text (required), project_id (required), work_item_id (required).

add_dependencyA

Make work_item_id depend on (be blocked by) predecessor_id. The successor can't be completed until the predecessor is done.

Inputs: project_id (required), work_item_id (required), predecessor_id (required).

add_design_element_commentA

Add a comment/note to a design element (markdown supported, max 5000 chars).

Inputs: text (required), element_id (required), project_id (required).

add_subtaskB

Add one sub-task (checklist item) to a work item.

Inputs: title (required), project_id (required), work_item_id (required).

assign_userC

Assign a project user to a work item.

Inputs: user_id (required), project_id (required), work_item_id (required).

attach_tagC

Attach an existing tag to a work item.

Inputs: tag_id (required), project_id (required), work_item_id (required).

close_boardC

Close (end) a board/sprint.

Inputs: board_id (required), project_id (required).

close_milestoneA

Close (release) a milestone — marks it done without deleting it. Reverse with reopen_milestone.

Inputs: project_id (required), milestone_id (required).

close_projectA

Close (archive) a project without deleting it — its work items and history are preserved. Reverse with reopen_project.

Inputs: project_id (required).

create_boardA

Create a board (sprint/iteration). Optionally nest under a milestone and set start/due dates (ISO 8601).

Inputs: name (required), project_id (required), due_date, start_date, +2 more.

create_categoryC

Create a work-item category.

Inputs: name (required), project_id (required), color.

create_design_elementA

Create a design element (a node in the design/feature tree). type_id is a design-element type id; parent_id nests it under another element (omit for a root). Link work items to it so progress rolls up the tree.

Inputs: name (required), type_id (required), project_id (required), parent_id, +1 more.

create_design_element_typeB

Create a design-element type (a node category for the design/feature tree).

Inputs: name (required), project_id (required), icon, color.

create_importance_levelC

Create an importance/priority level (color+icon).

Inputs: name (required), project_id (required), icon, color, +1 more.

create_milestoneC

Create a milestone. due_date is ISO 8601 (e.g. '2026-06-30T00:00:00Z').

Inputs: name (required), project_id (required), due_date, general_info.

create_projectA

Create a project. cost_metric is the STRING "Hours" or "Points" (capitalized). workspaceId is auto-assigned to your personal workspace (echoed back as 0). Returns the new project.

Inputs: name (required), cost_metric, description, hours_per_day.

create_stageA

Create a kanban stage. status must be one of (lowercase): created | started | completed. Both color AND icon are required by the API (omitting icon returns HTTP 500); icon is a HacknPlan icon name (e.g. inbox, wrench, check, rocket, eye, ban).

Inputs: name (required), project_id (required), icon, color, +2 more.

create_tagC

Create a tag (label).

Inputs: name (required), project_id (required), color.

create_work_itemA

Create a work item (task or user story). Required: title + importance_level_id (get it from get_project/list_*). category_id is required for tasks (not user stories). parent_id nests this item under a user story (the story→task hierarchy). assigned_user_ids assigns members; dependency_ids makes it blocked-by those items. sub_tasks is a list of checklist item titles. due_date/start_date are ISO 8601. If stage_id is given, the item is moved to that stage after creation (the API always creates new items in the default/first stage).

Inputs: title (required), project_id (required), importance_level_id (required), tag_ids, +12 more.

delete_categoryA

Delete a work-item category. Destructive. confirm=true required. (Useful to remove the game-dev defaults — Audio, Narrative, etc.)

Inputs: project_id (required), category_id (required), confirm.

delete_design_elementA

Delete a design element (and its sub-tree). Destructive. confirm=true required.

Inputs: element_id (required), project_id (required), confirm.

delete_milestoneA

Delete a milestone. Destructive (work items are un-grouped, not deleted). confirm=true required.

Inputs: project_id (required), milestone_id (required), confirm.

delete_projectA

Delete an ENTIRE project and everything in it. Destructive — set confirm=true.

Inputs: project_id (required), confirm.

delete_stageA

Delete a stage. Destructive (a project needs >=3 stages, one per status). confirm=true required.

Inputs: stage_id (required), project_id (required), confirm.

delete_subtaskC

Delete a sub-task. confirm=true required.

Inputs: project_id (required), subtask_id (required), work_item_id (required), confirm.

delete_tagA

Delete a tag. Destructive (removes it from all work items). confirm=true required.

Inputs: tag_id (required), project_id (required), confirm.

delete_work_itemA

Delete a work item. Destructive — set confirm=true to proceed.

Inputs: project_id (required), work_item_id (required), confirm.

detach_tagA

Remove a tag from a work item.

Inputs: tag_id (required), project_id (required), work_item_id (required).

find_work_itemsA

Search a project's work items by free text and/or facets — the name-based lookup that saves chaining list→scan→act. query matches title or description (case-insensitive). Optional facet filters: importance (level name e.g. 'Urgent'), tag (name), stage (name). status: open|closed|all (default open). Use this to resolve a task you only know by name into its id before update_work_item / move / etc.

Inputs: project_id (required), tag, limit, query, +4 more.

get_board_metricsA

Get a board's (sprint's) metrics — burndown / velocity / completion. Optionally scope to one user via user_id.

Inputs: board_id (required), project_id (required), user_id.

get_design_elementB

Get one design element (with its documentation/description).

Inputs: element_id (required), project_id (required).

get_design_element_metricsA

Get a design element's metrics (work rolled up from items linked to it). include_children rolls up its whole sub-tree.

Inputs: element_id (required), project_id (required), include_children.

get_milestone_metricsB

Get a milestone's metrics (burndown / completion).

Inputs: project_id (required), milestone_id (required).

get_projectA

Get one project with its stages, categories, importance levels and boards rolled up — the structural overview you need before creating work items.

Inputs: project_id (required).

get_project_metricsB

Get a project's metrics (completion %, totals) — analytics Trello lacks.

Inputs: project_id (required).

get_work_itemA

Get one work item with its sub-tasks (checklist) and comments.

Inputs: project_id (required), work_item_id (required).

hacknplan_whoamiA

Return the authenticated HacknPlan user (id, username, email, name). Use first to confirm the API key works.

Inputs: no named parameters.

list_attachmentsB

List the attachments on a work item.

Inputs: project_id (required), work_item_id (required).

list_boardsA

List a project's boards (sprints/kanban boards). The default is 'Sprint 1'. Closed boards are hidden unless include_closed=true.

Inputs: project_id (required), format, include_closed.

list_dependenciesB

List a work item's dependencies (the predecessors that block it).

Inputs: project_id (required), work_item_id (required).

list_design_element_commentsA

List the comments/notes on a design element (design-doc discussion thread).

Inputs: element_id (required), project_id (required).

list_design_elementsB

List design elements (nodes of the design/feature/knowledge tree). Optionally filter by type_id.

Inputs: project_id (required), type_id.

list_design_element_typesB

List the design-element TYPES (node categories of the design model, e.g. System / Module / Feature). Repurpose as a feature-tree taxonomy.

Inputs: project_id (required).

list_importance_levelsA

List a project's importance/priority levels (Urgent/High/Normal/Low by default).

Inputs: project_id (required), format.

list_milestonesA

List a project's milestones (release/epic groupings). Closed milestones are hidden unless include_closed=true.

Inputs: project_id (required), format, include_closed.

list_projectsB

List all HacknPlan projects.

Inputs: format.

list_project_usersA

List the members of a project (id, username).

Inputs: project_id (required).

list_stagesC

List a project's stages (kanban columns). status is created|started|completed.

Inputs: project_id (required), format.

list_subtasksA

List a work item's sub-tasks (its checklist), with completion state.

Inputs: project_id (required), work_item_id (required).

list_work_itemsA

List/search a project's work items with server-side filters. All filters are optional and AND-combined: board_id, stage_id, category_id, milestone_id, importance_level_id, tag_id, design_element_id, assigned_user_id, is_story, status ('open'|'closed'), text (free-text match). Paginated via limit/offset. For a forgiving name-based search that also works if a filter is unsupported, use find_work_items.

Inputs: project_id (required), text, limit, format, +11 more.

list_work_logsA

List the work logs (time entries) on a work item.

Inputs: project_id (required), work_item_id (required).

list_workspacesA

List HacknPlan workspaces visible to the API key. NOTE: Personal/Personal-Plus accounts return an empty list even though a 'Personal workspace' exists in the web UI — projects still work and are auto-assigned to it. Only Studio workspaces appear here.

Inputs: no named parameters.

log_workA

Log time/effort on a work item. value = amount worked, in the project's costMetric unit (hours or points). comment is an optional note. Logs can only be edited within ~1 hour of creation.

Inputs: value (required), project_id (required), work_item_id (required), comment.

my_workA

List work items assigned to the authenticated user (from /users/me), optionally scoped to one project — the 'what am I working on' / standup view. By default only open items; set include_closed=true to see finished ones too. Relies on the assignee data the list endpoint returns inline.

Inputs: format, project_id, include_closed.

plan_featureA

Break a feature down in ONE call: create a user story, then create its child tasks (parented to the story) — optionally each with its own checklist (sub_tasks). Tasks inherit importance_level_id, default_category_id, board_id and milestone_id unless overridden per task. This is the fast path for 'turn this feature into a story with tasks'. Returns the created story and tasks.

Inputs: project_id (required), story_title (required), importance_level_id (required), tasks, +5 more.

portfolio_overviewA

ALL-PROJECTS birds-eye view — the cross-project portfolio dashboard HacknPlan has no native equivalent for. Rolls up every project: completion %, open/closed counts, and urgent / blocked / due-soon / overdue flags, grouped via HACKNPLAN_GROUPS. Use for 'how's everything doing', 'what's on fire across all projects', 'portfolio status'.

Inputs: format.

recent_activityA

Project activity/event feed — the 'what changed' / standup view. Returns events between from and to (ISO 8601 dates/timestamps). If from is omitted it defaults to 7 days ago, to to now. Use for 'what happened this week', 'recent changes', daily standups.

Inputs: project_id (required), to, from.

remove_dependencyA

Remove a dependency from a work item. confirm=true required.

Inputs: project_id (required), work_item_id (required), dependency_id (required), confirm.

reopen_boardA

Reopen a previously closed board/sprint (counterpart to close_board).

Inputs: board_id (required), project_id (required).

reopen_milestoneB

Reopen a previously closed milestone.

Inputs: project_id (required), milestone_id (required).

reopen_projectA

Reopen a previously closed/archived project.

Inputs: project_id (required).

schedule_overviewA

ALL-PROJECTS deadline countdown — every work item that has a due date, across every project, bucketed by time horizon (Overdue / This week ≤7d / Next 2 weeks 8-14d / This month 15-30d / Later) with a live days-left countdown. Use for 'what's due soon', 'what's overdue', 'deadlines', 'what should I do this week'.

Inputs: format.

unassign_userB

Remove a user assignment from a work item.

Inputs: user_id (required), project_id (required), work_item_id (required).

update_boardA

Update a board/sprint (rename, change start/due date, description, or re-nest under a milestone). Dates are ISO 8601.

Inputs: board_id (required), project_id (required), name, due_date, +3 more.

update_categoryC

Update a work-item category (re-name / re-color / re-icon).

Inputs: name (required), project_id (required), category_id (required), icon, +1 more.

update_design_elementA

Update a design element (rename, edit documentation, re-parent, change type). type_id and name are required by the API; pass the element's current values to keep them. Use get_design_element first to read them.

Inputs: name (required), type_id (required), element_id (required), project_id (required), +2 more.

update_importance_levelB

Update an importance level (re-name / re-color / re-icon / set default).

Inputs: name (required), project_id (required), importance_level_id (required), icon, +2 more.

update_milestoneB

Update a milestone (rename, change due/start date, edit general info). Dates are ISO 8601.

Inputs: project_id (required), milestone_id (required), name, due_date, +2 more.

update_projectA

Update a project's name / description / cost metric ("Hours" or "Points").

Inputs: project_id (required), name, cost_metric, description.

update_stageA

Update a kanban stage (re-name / re-color / re-icon / change status). status: created | started | closed (lowercase). color is hex; icon is a HacknPlan icon name (e.g. inbox, wrench, check, rocket, eye, ban).

Inputs: name (required), status (required), stage_id (required), project_id (required), +3 more.

update_subtaskB

Update a sub-task (rename and/or mark complete/incomplete).

Inputs: title (required), project_id (required), subtask_id (required), work_item_id (required), +1 more.

update_tagA

Update a tag (re-name / re-color / re-icon / toggle icon-only display).

Inputs: name (required), tag_id (required), project_id (required), icon, +2 more.

update_work_itemA

Partially update a work item: move stage, retitle, edit description, set start/due date, block/unblock, retag, re-prioritize (importance_level_id), recategorize (category_id), re-estimate (estimated_cost), move board/milestone, re-parent, or reassign (assigned_user_ids replaces the whole assignee set). Provide only the fields you want to change.

Inputs: project_id (required), work_item_id (required), title, tag_ids, +12 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.2/5.0

Scored 2026-07-31 14:55 across 75 tools

Disambiguation5/5

Each tool targets a distinct resource and action (e.g., create_work_item vs. update_work_item vs. delete_work_item), and even similar operations like list_work_items, find_work_items, and my_work are clearly differentiated by their descriptions. The naming and descriptions make the purpose of each tool unambiguous, despite the large number of tools.

Naming Consistency4/5

The majority of tools follow a consistent snake_case verb_noun pattern (create_, update_, list_, get_, delete_, etc.). A few tools like portfolio_overview, schedule_overview, recent_activity, hacknplan_whoami, and my_work deviate from this pattern but remain in snake_case and are still readable and logically named.

Tool Count1/5

With 75 tools, this server far exceeds the typical well-scoped MCP server size of 3-15 tools and even the 25+ threshold for 'too many'. While the breadth reflects the full HacknPlan API, this is an extreme number that would overwhelm an agent and make tool selection unwieldy.

Completeness4/5

The tool set provides comprehensive CRUD coverage for most core resources: projects, stages, categories, tags, importance levels, boards, milestones, work items, subtasks, dependencies, comments, and design elements. A few minor gaps exist, such as lacking attachment upload/delete, user management within a project, and the ability to edit or delete comments, but the overall lifecycle is well-covered.

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Moxboard
app.moxboard
Simple kanban for small teams. Read and update your Moxboard boards and tasks from Claude.
Project Management Workplace & Productivity
1
https://app.moxboard.app/mcp
WithNettleB
com.withnettle
Project management shared by people and AI agents, with persistent project state through MCP.
Project Management Knowledge & Memory
1
https://withnettle.com/mcp
LooperTask
com.loopertask
AI-native Kanban board — connect Claude to claim, work and move your tasks over MCP.
Project Management Workplace & Productivity
1
https://loopertask.com/mcp
TimequipA
com.timequip
Manage Timequip projects, tasks, comments, members, and dashboards through MCP.
Project Management Workplace & Productivity
281
https://mcp.timequip.com/mcp

Related MCP Servers

Planka MCP Server for Claude
Project Management Workplace & Productivity
NextHeberg
A
license
Not graded
quality
D
maintenance
Enables AI-powered project management by connecting Claude to Planka kanban boards via 75+ MCP tools for creating, updating, and managing projects, boards, lists, and cards.
Updated 6 months ago (2026-05-23 13:11 UTC)
1
GPL 3.0
HAOps MCP Server
Project Management Communication
tbranzov
A
license
A
quality
B
maintenance
Enables Claude to interact with the HAOps project management system for managing projects, modules, features, and issues.
Updated 22 days ago (2026-10-24 09:37 UTC)
100
MIT
HacknPlan MCP Server
Project Management Games & Gamification
Lint111
A
license
B
quality
D
maintenance
Enables AI assistants to manage game development projects, sprints, tasks, and design documents via the HacknPlan API.
Updated a year ago (2025-12-23 17:26 UTC)
91
7
MIT
HacknPlan MCP
Project Management Games & Gamification
jompereira
F
license
C
quality
D
maintenance
Enables Claude to manage game development projects on HacknPlan, including tasks, boards, milestones, and GDD documents through natural language.
Updated 5 months ago (2026-06-23 09:07 UTC)
100
3
-

@mtuska/hacknplan-mcp

Quick start

The bundled skill (auto-updating)

Getting an API key

Install options

Manual configuration

Environment variables

Tools

Development

Publishing

License

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Planka MCP Server for Claude

HAOps MCP Server

HacknPlan MCP Server

HacknPlan MCP