README.md
TypeScript MCP server for Codecks project management
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
Tools (5)
list_cardsList and filter cards with pagination support.create_cardCreate a new card, including support for sub-cards.mark_doneMark specific cards as completed.list_activityRetrieve the recent activity feed from your projects.standupGenerate a daily standup summary.Environment Variables
CODECKS_TOKENrequiredSession cookie token from Browser DevToolsCODECKS_ACCOUNTrequiredYour Codecks account slugCODECKS_REPORT_TOKENToken generated via CLI commandCODECKS_USER_IDUser ID, auto-discovered if unsetConfiguration
claude_desktop_config.json
{"mcpServers": {"codecks": {"command": "npx", "args": ["-y", "codecks-mcp"]}}}Try it
→List all cards currently in my personal work queue.
→Create a new card in the development deck titled 'Fix authentication bug'.
→Give me a summary of my daily standup based on recent activity.
→Mark the card with ID 123 as done.
→Show me the current PM focus dashboard to see if any cards are stale.