README.md
Interact with Codecks project management directly from AI assistants.
Codecks MCP Server
An MCP (Model Context Protocol) server that lets AI assistants interact with Codecks project management. Query cards, create tasks, update status, and manage your game dev workflow directly from Claude or other MCP-compatible AI tools.
Repository: github.com/microkorg/Codecks-MCP
Features
- List & Search Cards - Query all cards or filter by deck/project/status, search by title/content
- Create Cards & Decks - Add new tasks directly from your AI assistant, reference decks by name or ID
- Update Cards - Modify card content, move between decks, rename decks
- Status Management - Mark cards complete, archive/unarchive finished work
- Space Management - List, create, rename, and delete spaces (deck containers)
- Flexible Project Filtering - Set a default project or specify per-call for cross-project workflows
Prerequisites
Quick Start
git clone https://github.com/microkorg/Codecks-MCP.git
cd Codecks-MCP
Then run the setup script for your platform:
- Windows:
setup.bat - Mac/Linux:
bash setup.sh
This installs dependencies and creates your .env config file. See Configuration below for how to find your token and user ID.
Configuration
Edit .env with your Codecks credentials:
# Required: Your auth token (see below for how to find it)
CODECKS_TOKEN=your_token_here
# Required: Your Codecks organization URL
CODECKS_URL=yourteam.codecks.io
# Optional: Default project filter (can be overridden per-call)
CODECKS_DEFAULT_PROJECT=My Project
# Required for create/update operations
CODECKS_USER_ID=your_user_id_here
Finding Your Token
- Open your Codecks organization in your browser
- Press F12 to open Developer Tools
- Go to Application tab > Cookies > your codecks domain
- Find the cookie named
atand copy its value
Finding Your User ID
- Open Developer Tools (F12) > Network tab
- Create any card in Codecks
- Find the request to
api.codecks.io/dispatch/cards/create - Look at the request payload - the
userIdfield is your user ID
Usage with Claude Code
Add to your .claude/settings.json:
{
"mcpServers": {
"codecks": {
"command": "node",
"args": ["/path/to/codecks-mcp/index.js"],
"cwd": "/path/to/codecks-mcp"
}
}
}
Optionally, prevent Claude from reading your credentials:
{
"deny": ["path/to/codecks-mcp/.env"]
}
Available Tools
Cards
| Tool | Description |
|---|---|
codecks_list_cards |
List all cards, optionally filter by deck name, project, and/or status |
codecks_search_cards |
Search cards by title or content |
codecks_get_card |
Get a specific card by ID |
codecks_create_card |
Create a new card in a deck (by ID or name) |
codecks_update_card |
Update card content |
codecks_move_card |
Move a card to a different deck |
codecks_complete_card |
Mark a card as complete or incomplete |
codecks_archive_card |
Archive a card |
codecks_unarchive_card |
Unarchive a card, making it visible again |
Decks
| Tool | Description |
|---|---|
codecks_list_decks |
List all decks in a project with card counts and space info |
codecks_create_deck |
Create a new deck, optionally in a specific space |
codecks_update_deck |
Rename a deck |
Spaces
| Tool | Description |
|---|---|
codecks_list_spaces |
List all spaces in a project |
codecks_create_space |
Create a new space (deck container) |
codecks_rename_space |
Rename a space |
codecks_delete_space |
Delete a space (cannot delete the default space) |
Projects
| Tool | Description |
|---|---|
codecks_list_projects |
List all projects in your organization |
codecks_create_project |
Create a new project |
Example Prompts
Once configured, you can ask Claude things like:
- "What cards are in my backlog?"
- "Show me all started cards"
- "Create a card for implementing the save system in the Ideas deck"
- "Mark the authentication card as complete"
- "Move the UI polish card to the In Progress deck"
- "Show me all cards in the other project"
- "Create a deck called 'Sprint 1' in the Design space"
- "What spaces are in this project?"
- "Rename the Art deck to Art Assets"
Token Expiration
The at cookie token may expire. If you start getting authentication errors, grab a fresh token from your browser cookies.
License
MIT
Tools (18)
codecks_list_cardsList all cards, optionally filter by deck name, project, and/or statuscodecks_search_cardsSearch cards by title or contentcodecks_get_cardGet a specific card by IDcodecks_create_cardCreate a new card in a deckcodecks_update_cardUpdate card contentcodecks_move_cardMove a card to a different deckcodecks_complete_cardMark a card as complete or incompletecodecks_archive_cardArchive a cardcodecks_unarchive_cardUnarchive a card, making it visible againcodecks_list_decksList all decks in a project with card counts and space infocodecks_create_deckCreate a new deck, optionally in a specific spacecodecks_update_deckRename a deckcodecks_list_spacesList all spaces in a projectcodecks_create_spaceCreate a new spacecodecks_rename_spaceRename a spacecodecks_delete_spaceDelete a spacecodecks_list_projectsList all projects in your organizationcodecks_create_projectCreate a new projectEnvironment Variables
CODECKS_TOKENrequiredYour Codecks auth tokenCODECKS_URLrequiredYour Codecks organization URLCODECKS_USER_IDrequiredYour Codecks user IDCODECKS_DEFAULT_PROJECTDefault project filterConfiguration
claude_desktop_config.json
{"mcpServers": {"codecks": {"command": "node", "args": ["/path/to/codecks-mcp/index.js"], "cwd": "/path/to/codecks-mcp"}}}Try it
→What cards are in my backlog?
→Show me all started cards
→Create a card for implementing the save system in the Ideas deck
→Mark the authentication card as complete
→Move the UI polish card to the In Progress deck