codecks-mcp

TypeScript MCP server for Codecks project management. Exposes 32+ tools for managing cards, decks, milestones, tags, and PM workflows via the Model Context Protocol.

Built with @modelcontextprotocol/server, zod, and Express.

Quick Start

# Run directly (no install needed)
npx codecks-mcp

# Or install globally
npm install -g codecks-mcp
codecks-mcp

Configuration

Create a .env file in your working directory:

CODECKS_TOKEN=your_session_cookie
CODECKS_ACCOUNT=your_account_slug

Tokens

Variable	Source	Expires
CODECKS_TOKEN	Browser DevTools > Cookie at	Yes
CODECKS_REPORT_TOKEN	CLI generate-token command	No
CODECKS_ACCOUNT	Your Codecks account slug	N/A
CODECKS_USER_ID	Auto-discovered if unset	N/A

Optional Settings

Variable	Default	Description
CODECKS_MCP_RESPONSE_MODE	legacy	legacy or envelope
CODECKS_HTTP_TIMEOUT_SECONDS	30	Request timeout
CODECKS_HTTP_MAX_RETRIES	2	Retry count

Transports

stdio (default)

codecks-mcp

HTTP

codecks-mcp --transport http --port 3000

Endpoints:

• POST /mcp — MCP protocol (Streamable HTTP)
• GET /ping — Health check

IDE Setup

Claude Code

{
  "mcpServers": {
    "codecks": {
      "command": "npx",
      "args": ["-y", "codecks-mcp"]
    }
  }
}

Cursor

{
  "mcpServers": {
    "codecks": {
      "command": "npx",
      "args": ["-y", "codecks-mcp"]
    }
  }
}

Remote (HTTP)

{
  "mcpServers": {
    "codecks": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Tools

Read (10)

Tool	Description
get_account	Current account info
list_cards	List/filter cards with pagination
get_card	Full card details
list_decks	All decks
list_projects	Projects with decks
list_milestones	Milestones
list_tags	Project-level tags
list_activity	Recent activity feed
pm_focus	PM dashboard (blocked, stale, suggested)
standup	Daily standup summary

Hand (3)

Tool	Description
list_hand	Personal work queue
add_to_hand	Add cards to hand
remove_from_hand	Remove cards from hand

Mutation (9)

Tool	Description
create_card	Create card (supports sub-cards)
update_cards	Batch update properties
mark_done	Mark cards done
mark_started	Mark cards started
archive_card	Archive (reversible)
unarchive_card	Restore archived
delete_card	Permanent delete
scaffold_feature	Hero + lane sub-cards
split_features	Batch-split features

Comments (5)

Tool	Description
create_comment	Start thread
reply_comment	Reply to thread
close_comment	Resolve thread
reopen_comment	Reopen thread
list_conversations	List threads

PM Session (3)

Tool	Description
get_pm_playbook	Methodology guide
get_workflow_preferences	Load preferences
save_workflow_preferences	Save preferences

Feedback (2)

Tool	Description
save_cli_feedback	Save feedback
get_cli_feedback	Read feedback

Security

• Prompt injection detection (6 regex patterns)
• [USER_DATA] boundary tagging on user-authored content
• Input validation with zod schemas + length limits
• UUID validation on all card IDs
• Control character stripping

Development

# Install
pnpm install

# Dev mode (tsx, auto-reload)
pnpm dev

# Build
pnpm build

# Test
pnpm test

# Lint + format
pnpm lint
pnpm format:check

# Type check
pnpm typecheck

Also Available

• Python version: codecks-mcp-python — same tools, Python runtime
• Full CLI: codecks-cli — CLI + library with formatters, GDD sync, and more

License

MIT