# Codecks MCP Server

An MCP (Model Context Protocol) server that lets AI assistants interact with [Codecks](https://codecks.io) 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](https://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

- [Node.js](https://nodejs.org/) v18 or later
- A [Codecks](https://codecks.io) account with an organization

## Quick Start

```bash
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](#configuration) below for how to find your token and user ID.

## Configuration

Edit `.env` with your Codecks credentials:

```env
# 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

1. Open your Codecks organization in your browser
2. Press F12 to open Developer Tools
3. Go to **Application** tab > **Cookies** > your codecks domain
4. Find the cookie named `at` and copy its value

### Finding Your User ID

1. Open Developer Tools (F12) > **Network** tab
2. Create any card in Codecks
3. Find the request to `api.codecks.io/dispatch/cards/create`
4. Look at the request payload - the `userId` field is your user ID

## Usage with Claude Code

Add to your `.claude/settings.json`:

```json
{
  "mcpServers": {
    "codecks": {
      "command": "node",
      "args": ["/path/to/codecks-mcp/index.js"],
      "cwd": "/path/to/codecks-mcp"
    }
  }
}
```

Optionally, prevent Claude from reading your credentials:

```json
{
  "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