Content
# Kaiten MCP Server
> MCP server for working with tasks [Kaiten](https://kaiten.ru/) through AI-agents (Claude Code, Claude Desktop, etc.)
[](./STATUS.md)
[](https://www.typescriptlang.org/)
[](https://github.com/modelcontextprotocol)
## 🎯 Features
Kaiten MCP Server provides AI-agents (Claude) with access to your tasks in Kaiten through [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).
**Implemented tools:**
- ✅ **get-task-details** — get detailed information about a task (description, comments, participants)
- ✅ **get-task-status** — quick check of the status of one or several tasks
- ✅ **get-time-logs** — time accounting for a task with grouping by users/days
- ✅ **create-task** — creation of new tasks on the board
- ✅ **update-task** — updating existing tasks (title, description, moving, assignment)
**In development (roadmap):**
- 🔥 **get-board-cards** — list of tasks on the board with filtering (critical)
- **get-board-structure** — board structure (columns, lanes, tags)
- **delete-task**, **add-comment**, **log-time** and [other features](./specs/roadmap.md)
## 📋 Requirements
- **Node.js** >= 20
- **Kaiten API token** (created in profile: Settings → API tokens)
- **Access to Kaiten API** of your organization
## 🚀 Installation
### 1. Cloning and building
```bash
git clone git@github.com:Happiest-d/kaiten-mcp.git
cd kaiten-mcp
npm install
npm run build
```
### 2. Environment variable setup
Two variables are required:
| Variable | Description | Example |
|------------|----------|--------|
| `KAITEN_API_TOKEN` | API token from Kaiten profile | `abc123def456...` |
| `KAITEN_BASE_URL` | Full URL of your Kaiten API | `https://mycompany.kaiten.ru/api/latest` |
**Getting token:**
1. Open Kaiten
2. Profile → Settings → API tokens
3. Create a new token
### 3. Connecting to Claude Code
Add to `~/.claude/mcp.json` or `.mcp.json` of your project:
```json
{
"mcpServers": {
"kaiten": {
"command": "node",
"args": ["/path/to/kaiten-mcp/dist/src/index.js"],
"env": {
"KAITEN_API_TOKEN": "your_token",
"KAITEN_BASE_URL": "https://yourcompany.kaiten.ru/api/latest"
}
}
}
}
```
**For Claude Desktop**, use a similar configuration in the application settings.
After restarting Claude, it will have access to all MCP tools for working with Kaiten.
## 🛠️ Available tools (MCP Tools)
### `get-task-details`
Gets detailed information about a task: description, participants, comments, metadata.
```json
{
"card_id": 12345,
"include_comments": true,
"comments_limit": 20
}
```
**Returns:** title, description, state, owner, members, tags, comments (with pagination), created_at, updated_at
### `get-task-status`
Quick check of task status (up to 50 at a time).
```json
{
"card_ids": [12345, 67890]
}
```
**Returns:** card_id, title, board_id, column_id, state, updated_at for each card
### `get-time-logs`
Gets time accounting logs for a task with grouping.
```json
{
"card_id": 12345,
"group_by": "user"
}
```
**Grouping modes:**
- `"none"` — flat list of all entries
- `"user"` — grouping by users
- `"date"` — grouping by days
**Returns:** total_minutes, entries (with details: user_id, time_spent, for_date, comment)
### `create-task`
Creates a new task on the board.
```json
{
"title": "Fix authorization bug",
"description": "Users cannot log in via OAuth...",
"board_id": 1660008,
"column_id": 5747562,
"position": 1
}
```
**Returns:** card_id, title, board_id, column_id, state, created_at
### `update-task`
Updates an existing task (title, description, moving, assignment).
```json
{
"card_id": 12345,
"title": "New title",
"column_id": 5747563,
"owner_id": 501
}
```
**Supported updates:**
- Renaming (`title`)
- Changing description (`description`)
- Moving between columns (`column_id`)
- Moving between lanes (`lane_id`)
- Reassigning executor (`owner_id`)
- Changing participants (`members`)
- Changing tags (`tags`)
**Returns:** full updated card with all fields
## 📁 Project structure
```
kaiten-mcp/
├── src/
│ ├── index.ts # MCP server entry point
│ ├── server.ts # Configuration and tool registration
│ ├── kaiten/
│ │ ├── client.ts # HTTP client for Kaiten API
│ │ └── types.ts # TypeScript types and mappings
│ └── tools/ # MCP tools (one file = one tool)
│ ├── get-task-details.ts
│ ├── get-task-status.ts
│ ├── get-time-logs.ts
│ ├── create-task.ts
│ └── update-task.ts
├── tests/ # Unit tests (Vitest)
│ ├── kaiten/
│ └── tools/
├── specs/ # Feature specifications
│ ├── roadmap.md # Full project roadmap
│ └── *.md # Detailed specs for each feature
├── MANUAL.md # User documentation
├── STATUS.md # Current project status (features, tests)
└── CLAUDE.md # Development standards, TDD, architecture
```
## 🧪 Development
### Running tests
```bash
npm test # All tests (78 tests)
npm test -- get-task # Specific file
```
**Current status:** 78/78 tests pass ✅
### Building
```bash
npm run build # TypeScript compilation
npm run lint # ESLint check
```
### Methodology: TDD (Test-Driven Development)
The project follows a strict TDD cycle:
1. **RED** — write a failing test first
2. **GREEN** — write minimal code to pass the test
3. **REFACTOR** — refactor with preserved green tests
Each feature starts with a specification in `specs/`, then tests are written, then implementation.
### Stack
- **TypeScript** (strict mode)
- **MCP SDK** v1.26+ (Model Context Protocol)
- **Zod v4** — schema validation
- **Vitest** — testing
- **ESLint** — linting
## 📚 Documentation
- **[MANUAL.md](./MANUAL.md)** — detailed user guide (parameters, examples)
- **[STATUS.md](./STATUS.md)** — current feature status, tests, infrastructure
- **[CLAUDE.md](./CLAUDE.md)** — code standards, architecture, TDD workflow
- **[specs/roadmap.md](./specs/roadmap.md)** — full roadmap with 17 features and priorities
## 🗺️ Roadmap
**Implemented (5/17 features):**
- ✅ get-task-details, get-task-status, get-time-logs
- ✅ create-task, update-task
**Priority:**
1. 🔥 **get-board-cards** — list of tasks on the board with filtering (critical for navigation)
2. **get-board-structure** — board structure (columns, lanes, tags)
3. **delete-task** / **archive-task** — task deletion/archiving
4. **add-comment** — adding comments
5. **log-time** — time accounting
Full list: [specs/roadmap.md](./specs/roadmap.md)
## 📝 License
MIT
## 🤝 Contribution
The project follows strict TDD and spec-driven development standards:
1. Create an issue with feature description
2. Write specification in `specs/`
3. Write tests (RED phase)
4. Implement feature (GREEN phase)
5. Refactor (REFACTOR phase)
6. Create PR with updated documentation (STATUS.md, MANUAL.md)
See [CLAUDE.md](./CLAUDE.md) for details.
---
**Made with ❤️ for AI agents**
