Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@HacknPlan MCP Server create a new task for player movement system"
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.
A Model Context Protocol (MCP) server that provides a pure API wrapper for the HacknPlan project management API. Enables AI assistants like Claude to manage game development projects, sprints, tasks, and design documents.
🛡️ Deletion Recovery - 30-day recovery cache with crash resilience (v7.2.0)
⏱️ Automatic Time Tracking - Zero-effort time logging (v7.1.0+)
🚀 Context Optimization - 75-85% token reduction with slim mode + tool search
📦 Batch Operations - Update 1-100 items in a single call
🔍 Advanced Search - Multi-criteria filtering with name resolution
💾 Smart Caching - 80% fewer API calls with automatic 5-minute cache
Full feature list: Documentation →
Related MCP server: OpenProject MCP Server
git clone https://github.com/yourusername/hacknplan-mcp.git
cd hacknplan-mcp
npm install
npm run buildclaude mcp add hacknplan -s user \
-e HACKNPLAN_API_KEY=your-api-key \
-- node /path/to/hacknplan-mcp/dist/index.js// Create a task
await callTool('create_work_items', {
items: [{
title: 'Implement OAuth',
categoryId: 'programming', // Name resolution
importanceLevelId: 'high', // Name resolution
tagIds: ['backend', 'security'] // Auto-creates tags
}]
});
// Start working (automatic time tracking)
await callTool('start_task', { workItemId: 123 });
// Complete (auto-logs hours)
await callTool('complete_task', {
workItemId: 123,
comment: 'OAuth implementation complete'
});→ Complete Documentation Index
Guide | Description |
Your first API calls (5 min) | |
Task management reference | |
Automatic time logging | |
Recovery system | |
Real-world recipes |
Beginner: Installation → Configuration → Quick Start → Work Items
Intermediate: Time Tracking → Workflow Shortcuts → Batch Operations
Advanced: Slim Mode → Tool Search → Caching → Best Practices
// Create sprint
const sprint = await callTool('create_boards', {
boards: [{
name: 'Sprint 4: Authentication',
startDate: '2026-01-01T00:00:00Z',
endDate: '2026-01-14T23:59:59Z'
}]
});
// Get backlog and assign to sprint
const backlog = await callTool('get_backlog', {});
await callTool('update_work_items', {
items: backlog.items.slice(0, 10).map(item => ({
workItemId: item.workItemId,
boardId: sprint.items[0].boardId
}))
});// Start task (begins tracking)
await callTool('start_task', { workItemId: 123 });
// ... work for 2.5 hours ...
// Complete (auto-logs 2.5h)
await callTool('complete_task', {
workItemId: 123,
comment: 'Feature complete, tests passing'
});
// ✅ Automatically logged 2.5 hours// Create multiple tasks at once
await callTool('create_work_items', {
items: [
{ title: 'Design API', categoryId: 'design', estimatedCost: 4 },
{ title: 'Implement endpoints', categoryId: 'programming', estimatedCost: 8 },
{ title: 'Write tests', categoryId: 'programming', estimatedCost: 6 }
]
});
// ✅ 3 tasks created in 1 API callAll deletions automatically stored in recovery cache for 30 days:
// Delete with automatic recovery
await callTool('delete_work_items', { workItemIds: [123, 124, 125] });
// Later, recover if needed (up to 30 days)
await callTool('recover_deleted_items', { workItemIds: [123, 124, 125] });Slim Mode (75% token reduction):
HACKNPLAN_SLIM_MODE=true
HACKNPLAN_OUTPUT_VERBOSITY=slimTool Search (85% reduction on tool loading):
Loads only 8 core tools initially
Discovers 88 additional tools on-demand
Smart Caching (80% fewer API calls):
Automatic 5-minute cache on all GET requests
→ Documentation Index (docs/INDEX.md)
Projects - Project management
Boards & Sprints - Sprint planning
Work Items - Tasks, bugs, features
Comments - Markdown comments
Milestones - Major deliverables
Design Elements - Game design docs
Deletion Safety - Recovery system
Automatic Time Tracking - Zero-effort logging
Slim Mode - Context optimization
Array-Based API - Batch operations
Tool Search - Dynamic tool discovery
Workflow Shortcuts - Combined operations
Batch Operations - Search & analytics
Metadata & Config - Stages, tags, users
Caching - Performance optimization
Common Patterns - Real-world recipes
Error Handling - Error types & recovery
Best Practices - Optimization tips
HACKNPLAN_API_KEY=your-key # Required: API authentication
HACKNPLAN_DEFAULT_PROJECT=230954 # Optional: Default project ID
HACKNPLAN_SLIM_MODE=true # Optional: Enable 26-tool slim mode
HACKNPLAN_OUTPUT_VERBOSITY=slim # Optional: Minimal response fields
HACKNPLAN_DELETION_CACHE_SIZE=1000 # Optional: Recovery cache capacity→ Complete Configuration Guide
Contributions welcome! Please see:
Issues: GitHub Issues
Pull Requests: Follow standard GitHub PR workflow
Documentation: Help improve docs/
MIT License - See LICENSE for details
Documentation: docs/INDEX.md
API Reference: API-REFERENCE.md (Complete technical reference)
Claude.ai Guide: CLAUDE.md (AI assistant integration)
HacknPlan API: Official Docs
GitHub: yourusername/hacknplan-mcp
Need help?
Quick Start Guide - Get running in 5 minutes
Common Patterns - Real-world recipes
Error Handling - Troubleshooting guide
GitHub Issues - Report bugs or request features
Version: 7.2.0 | Last Updated: December 21, 2025
Add one or more comments to work items (array-based). Single-item and batch calls use the same interface. Returns unified response with items array, counts, and per-item errors.
Inputs: comments (required), projectId.
Add one or more dependencies between work items (array-based). Each item creates a dependency where the successor depends on the predecessor.
Inputs: items (required), projectId.
Assign a work item to the current user
Inputs: workItemId (required), projectId.
Stages work items for deletion and returns a confirmation request. No items are deleted until confirm_deletion is called with the confirmation token. Generates preview with warnings if deletion count exceeds cache capacity.
Inputs: workItemIds (required), projectId.
Cancel a staged deletion and release items from the confirmation queue. The items will not be deleted and the confirmation token will be invalidated.
Inputs: confirmationToken (required).
Clear cached data (metadata, work items, etc.). Use pattern to clear specific cache entries.
Inputs: pattern.
Clear recovery cache entries. Requires acknowledged="CLEAR" for safety. Optionally filter by project. WARNING: This removes recovery capability for deleted items.
Inputs: acknowledged (required), projectId.
Close one or more boards/sprints (array-based). Single-item and batch calls use the same interface. Returns unified response with items array, counts, and per-item errors.
Inputs: items (required), projectId.
Close one or more milestones (array-based). Single-item and batch calls use the same interface. Returns unified response with items array, counts, and per-item errors.
Inputs: items (required), projectId.
Close one or more projects (array-based). Single-item and batch calls use the same interface. Returns unified response with items array, counts, and per-item errors.
Inputs: items (required).
Complete a task in one call with optional time logging and comment. Atomically: marks task completed, optionally moves to completion stage, adds comment, and logs time. Supports name resolution for workItemId.
Inputs: workItemId (required), comment, projectId, hoursWorked, +1 more.
Execute a staged deletion after user confirmation. Requires the confirmation token from batch_delete_work_items and acknowledged must be "DELETE" or "CONFIRM".
Inputs: acknowledged (required), confirmationToken (required), authCode.
Create one or more boards/sprints (array-based). Single-item and batch calls use the same interface. Returns unified response with items array, counts, and per-item errors.
Inputs: boards (required), projectId.
Create one or more work item categories (array-based). Single-item and batch calls use the same interface. Returns unified response with items array, counts, and per-item errors.
Inputs: items (required), projectId.
Create one or more design elements (array-based). Single-item and batch calls use the same interface. Returns unified response with items array, counts, and per-item errors.
Inputs: items (required), projectId.
Create one or more design element types (array-based). Single-item and batch calls use the same interface. Returns unified response with items array, counts, and per-item errors.
Inputs: items (required), projectId.
Create work items from a template with variable substitution
Inputs: templateName (required), boardId, projectId, variables.
Create one or more milestones (array-based). Single-item and batch calls use the same interface. Returns unified response with items array, counts, and per-item errors.
Inputs: items (required), projectId.
Create one or more projects (array-based). Single-item and batch calls use the same interface. Returns unified response with items array, counts, and per-item errors.
Inputs: items (required).
Create one or more workflow stages (array-based). Single-item and batch calls use the same interface. Returns unified response with items array, counts, and per-item errors.
Inputs: items (required), projectId.
Create a subtask linked to a parent user story in a single call. Wraps create_work_item + set_work_item_parent. Inherits board from parent if not specified. Supports name resolution for category, importance, and tags.
Inputs: title (required), categoryId (required), parentWorkItemId (required), tagIds, +6 more.
Create one or more project tags (array-based). Single-item and batch calls use the same interface. Returns unified response with items array, counts, and per-item errors.
Inputs: items (required), projectId.
Create a work item atomically with all related operations in a single transaction. v4.5+ supports name resolution.
Inputs: title (required), categoryId (required), tagIds, boardId, +5 more.
Create one or more work items (array-based). Supports name resolution for categoryId, importanceLevelId, and tagIds. Single-item and batch calls use the same interface. Returns unified response with items array, counts, per-item errors, and warnings.
Inputs: items (required), projectId.
Delete a file attachment
Inputs: workItemId (required), attachmentId (required), projectId.
Delete one or more boards (array-based, DESTRUCTIVE). Single-item and batch calls use the same interface. Returns unified response with items array, counts, and per-item errors.
Inputs: items (required), projectId.
Delete one or more comments (array-based). Each item removes a comment from a work item.
Inputs: items (required), projectId.
Delete one or more design elements (array-based, DESTRUCTIVE). Single-item and batch calls use the same interface. Returns unified response with items array, counts, and per-item errors.
Inputs: items (required), projectId.
Delete one or more milestones (array-based, DESTRUCTIVE). Single-item and batch calls use the same interface. Returns unified response with items array, counts, and per-item errors.
Inputs: items (required), projectId.
Delete one or more projects (array-based, DESTRUCTIVE). Single-item and batch calls use the same interface. Returns unified response with items array, counts, and per-item errors.
Inputs: items (required).
Delete one or more workflow stages (array-based). Single-item and batch calls use the same interface. Returns unified response with items array, counts, and per-item errors.
Inputs: items (required), projectId.
Delete one or more work items (array-based, requires confirmation). Stages items for deletion and returns a confirmation token. Call confirm_deletion with the token to execute the deletion. Items are stored in recovery cache before deletion for potential recovery.
Inputs: workItemIds (required), projectId.
Download a file attachment to local disk
Inputs: savePath (required), workItemId (required), attachmentId (required), overwrite, +1 more.
Export recovery cache to JSON file. Supports project-specific export. Useful for backup or migration.
Inputs: filePath (required), projectId.
Get overview of currently active (open) sprints with task counts. Returns { boards: [...], totalActiveSprints }.
Inputs: projectId.
Get attachment metadata and download URL
Inputs: workItemId (required), attachmentId (required), projectId.
Get TRUE backlog items - work items with NO board/sprint assignment. Returns { items, total }. NOTE: Items in closed sprints are NOT backlog - they are archived work.
Inputs: projectId.
Analyze dependency graphs to identify blocking work items. Supports premium API + free-tier fallback (parses description markers). Returns items that are blocked by incomplete dependencies, optionally including transitive blockers. Can calculate critical path for a specific work item.
Inputs: projectId, workItemId, includeIndirect, useFallbackParser.
Get work items that are blocking this work item (predecessors that must complete first)
Inputs: workItemId (required), projectId.
Get details of a specific board
Inputs: boardId (required), projectId.
Get board metrics (burndown data, etc.)
Inputs: boardId (required), projectId.
Get the current authenticated user information
Inputs: no named parameters.
View recovery cache statistics including capacity, entries by project/status, and age ranges. Useful for monitoring cache health.
Inputs: projectId.
Get full dependency tree for a work item (all predecessors and successors)
Inputs: workItemId (required), projectId.
Get details of a design element
Inputs: designElementId (required), projectId.
Get all incomplete work items for a project or board. Returns { items, total }.
Inputs: boardId, projectId.
Get details of a specific milestone
Inputs: milestoneId (required), projectId.
Get current user's assigned tasks with aggregated statistics (by stage, by priority, total estimate). Returns slim work items for token efficiency. Supports both auto-fetch (all items) and manual pagination (offset/limit).
Inputs: limit, offset, boardId, projectId, +1 more.
Get work items assigned to the current user. Returns { items, total }.
Inputs: boardId, projectId.
Get details of a specific project
Inputs: projectId.
Get project metrics (completion stats, etc.)
Inputs: projectId.
Get comprehensive sprint progress metrics including burndown chart, dependency graph, and hour tracking. Provides rich data for sprint visualization and analysis.
Inputs: boardId (required), projectId.
Get a compressed summary of current sprint status with task counts by stage (highly optimized for token usage)
Inputs: boardId (required), projectId.
Get detailed information about a specific work item
Inputs: workItemId (required), projectId.
Get all child work items (subtasks) of a parent user story
Inputs: workItemId (required), projectId.
Import recovery cache from JSON file. Supports merge (add to existing) or replace (clear then import) modes. Validates file format.
Inputs: mode (required), filePath (required).
List file attachments for a work item with pagination
Inputs: workItemId (required), limit, offset, projectId.
List all boards (sprints) for a project. Returns { items, total, offset, limit, hasMore, index? }. In slim mode, includes index array of [id, name] pairs for all boards (not just current page).
Inputs: limit, offset, projectId, verbosity.
List available work item categories (Task, Bug, Feature, etc.). Returns { items, total, offset, limit, hasMore }.
Inputs: limit, offset, projectId.
List comments on a work item. Returns { items, total, offset, limit, hasMore }.
Inputs: workItemId (required), limit, offset, projectId.
List design elements (game design documents). Returns { items, total, offset, limit, hasMore }.
Inputs: limit, offset, typeId, projectId.
List design element types (e.g., Character, Item, Level). Returns { items, total, offset, limit, hasMore }.
Inputs: limit, offset, projectId.
List importance/priority levels for a project. Returns { items, total, offset, limit, hasMore }.
Inputs: limit, offset, projectId.
List milestones for a project. Returns { items, total, offset, limit, hasMore }.
Inputs: limit, offset, projectId.
List all HacknPlan projects accessible with your API key. Returns { items, total, offset, limit, hasMore, index? }. In slim mode, includes index array of [id, name] pairs for all projects (not just current page).
Inputs: limit, offset, verbosity.
List available stages (workflow states) for a project. Returns { items, total, offset, limit, hasMore }.
Inputs: limit, offset, projectId.
List project tags. Returns { items, total, offset, limit, hasMore }.
Inputs: limit, offset, projectId.
List available work item templates
Inputs: no named parameters.
List users in a project. Returns { items, total, offset, limit, hasMore }.
Inputs: limit, offset, projectId.
List work items with optional filters and pagination. Returns { items, total, offset, limit, index? }. In slim mode, includes index array of [id, name] pairs for all work items (not just current page).
Inputs: limit, tagId, offset, boardId, +6 more.
Log work time for one or more work items (array-based). Single-item and batch calls use the same interface. Returns unified response with items array, counts, total hours, and per-item errors. Note: Does not include automatic time tracking - use log_work_session for that.
Inputs: sessions (required), projectId.
Pause work on a task. Accumulates time from current session and allows working on other tasks without corrupting time tracking.
Inputs: workItemId (required), projectId.
Restore deleted work items from recovery cache. Creates new items (cannot restore original IDs). Handles double-recovery prevention, cross-project validation, and locked items.
Inputs: workItemIds (required), projectId.
Remove one or more dependencies between work items (array-based). Each item removes a dependency relationship.
Inputs: items (required), projectId.
Reopen one or more closed boards (array-based). Single-item and batch calls use the same interface. Returns unified response with items array, counts, and per-item errors.
Inputs: items (required), projectId.
Reopen one or more closed milestones (array-based). Single-item and batch calls use the same interface. Returns unified response with items array, counts, and per-item errors.
Inputs: items (required), projectId.
Reopen one or more closed projects (array-based). Single-item and batch calls use the same interface. Returns unified response with items array, counts, and per-item errors.
Inputs: items (required).
Resume work on a paused task. Starts a new session without losing accumulated time from previous sessions.
Inputs: workItemId (required), projectId.
Advanced search for work items with multiple filter criteria. Combines API filters with client-side filtering for comprehensive queries.
Inputs: tags, boardId, stageId, projectId, +11 more.
Set an image attachment as the work item card thumbnail (requires image file)
Inputs: workItemId (required), attachmentId (required), projectId.
Set the default project ID for this MCP server session. This overrides environment variables and .mcp.json config. Useful for switching between projects without restarting the server.
Inputs: projectId (required).
Set global output verbosity for all list operations. Controls whether list_projects, list_boards, and list_work_items return full or slim output by default.
Inputs: verbosity (required).
Move a task to "In Progress" stage with optional comment. Supports name resolution for workItemId (e.g., "Implement shader" or 123). Auto-detects "In Progress" stage or uses stageId override.
Inputs: workItemId (required), comment, stageId, projectId.
Update one or more boards (array-based). Single-item and batch calls use the same interface. Returns unified response with items array, counts, and per-item errors.
Inputs: items (required), projectId.
Update one or more comments (array-based). Each item updates a comment with new text.
Inputs: items (required), projectId.
Update one or more design elements (array-based). Single-item and batch calls use the same interface. Returns unified response with items array, counts, and per-item errors.
Inputs: items (required), projectId.
Update one or more milestones (array-based). Single-item and batch calls use the same interface. Returns unified response with items array, counts, and per-item errors.
Inputs: items (required), projectId.
Update one or more projects (array-based). Single-item and batch calls use the same interface. Returns unified response with items array, counts, and per-item errors.
Inputs: items (required).
Update one or more workflow stages (array-based). Single-item and batch calls use the same interface. Returns unified response with items array, counts, and per-item errors.
Inputs: items (required), projectId.
Update one or more work items (array-based). Supports auto-create for tags: when string names are provided and the tag does not exist, it will be created automatically. Consolidates all setter operations (assignedUserIds, tagIds, parentStoryId, designElementId) into a single call. Returns unified response with items array, counts, per-item errors, and warnings for auto-created tags.
Inputs: items (required), projectId.
Upload a file attachment to a work item
Inputs: filePath (required), workItemId (required), projectId, description.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 91 tools
Many tools have clearly distinct purposes, but there are overlapping pairs like get_my_current_tasks vs get_my_tasks, and multiple create work item tools (create_work_items, create_work_item_atomic, create_subtask, create_from_template) which may confuse an agent. The deletion workflow also has several steps (batch_delete_work_items, confirm_deletion, cancel_deletion) that could be grouped.
Naming largely follows a verb_noun pattern with underscores (e.g., create_work_items, list_projects). Minor inconsistencies include mixed verb prefixes (add_comments vs create_comments) and compound names like get_active_sprint_overview, but overall the pattern is predictable.
With 91 tools, the server is extremely heavy. Typical MCP servers have 3-15 tools; this is far beyond and likely to overwhelm agents. Many tools could be consolidated (e.g., batch operations combined with single-item calls).
The tool set covers nearly every aspect of the domain: full CRUD for work items, boards, milestones, projects, design elements, comments, attachments, dependencies, time tracking, user info, cache management, and even administrative controls like setting default project. No obvious gaps are apparent.
Create and manage MeisterTask projects, tasks, and notes from your AI assistant.
Manage Orangescrum projects, tasks, users, sprints, test cases, releases, and risks from AI tools.
Tasks, sprints, releases and docs for engineering teams with AI coding agents.
Manage Loom projects, tasks, bugs, defects, clients and phases from AI assistants
