Skip to main content
Glama
Yokan Board MCP
by yokan-board

Yokan Board MCP

This project is a Model Context Protocol (MCP) server for the Yokan Kanban Board API. It provides a tool-based interface for AI agents to interact with and manage Kanban boards, columns, and tasks.

Features

  • Board Management: Create, retrieve, update, and delete Kanban boards.

  • Column Management: Create, retrieve, update, reorder, and delete columns within a board.

  • Task Management: Create, retrieve, update, move, and delete tasks.

  • Agent-Ready: Designed to be used by AI agents via the Master Control Protocol.

Related MCP server: Wekan MCP Server

Tech Stack

Getting Started

Building and Running Docker Image

For new users or those who want to run the server without setting up a development environment, we recommend using Docker.

  1. Build the Docker image:

    docker build -t yokanboard/yokan-mcp .
  2. Run the Docker container:

    docker run -p 8888:8888 --name yokan-mcp -e YOKAN_API_BASE_URL=http://your-yokan-api-host:port/api yokanboard/yokan-mcp

    Make sure to replace http://your-yokan-api-host:port/api with the actual URL of your Yokan API instance.

MCP Clients Configuration

Gemini CLI with the Streamable Transport

Create .gemini/settings.json with the following content:

{
    "mcpServers": {
        "yokan-board": {
            "httpUrl": "http://[your-yokan-mcp-host]:8888/mcp",
            "headers": {
                "Authorization": "Bearer [TOKEN]",
                "accept": "application/json"
            }
        }
    }
}

VS Code Copilot with the Stdio Transport

Create .vscode/mcp.json file with the following content:

{
    "servers": {
        "yokan-board": {
            "type": "stdio",
            "command": "uv",
            "args": [
                "run",
                "--directory",
                "/full/path/to/yokan-board-mcp-project-folder/yokan-board-mcp",
                "-m",
                "src.main",
                "--stdio"
            ]
        }
    }
}

Development

Prerequisites

  • Python 3.8+

  • uv (for managing the Python environment)

  • Access to a running instance of the Yokan API.

Setup

  1. Clone the repository:

    git clone https://github.com/yokan-board/yokan-board-mcp.git
    cd yokan-board-mcp
  2. Create and activate a virtual environment:

    uv venv
    source .venv/bin/activate
  3. Install the dependencies:

    uv sync

Configuration

  1. Create a .env file by copying .env.example:

    cp .env.example .env
  2. Edit the .env file to point to your Yokan API instance:

    YOKAN_API_BASE_URL=http://your-yokan-api-host:port/api

Running the Server

To start the MCP server for development, run the following command:

uvicorn src.main:app --host localhost --port 8888 --reload

Testing

To run the integration tests, you need to have a running Yokan API instance and a test user. The tests are configured to use the username user and password password.

Make sure your .env file is correctly configured with the YOKAN_API_BASE_URL.

Run the tests using the following command:

make test

Available Tools

The MCP server exposes the following tools for managing a Yokan Kanban board:

Category

Tools

Boards

get_boards, get_board, create_board, update_board, delete_board

Columns

create_column, get_columns, update_column, reorder_columns, delete_column, update_column_color

Tasks

create_task, create_tasks, get_tasks, update_task, move_task, delete_task

Usage Examples

You can interact with the MCP server using the fastmcp client library.

Authentication

To use the tools, you first need to obtain a JWT token from your Yokan API instance. You can do this by sending a POST request to the /login endpoint of the Yokan API.

Example using curl:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"username": "your_username", "password": "your_password"}' \
  http://localhost:3001/api/v1.1/login

Example: Interacting with the MCP Server

A Python example demonstrating how to use the fastmcp client to interact with the Yokan MCP server can be found in examples/mcp_client.py.

Yokan Board MCP is created by: Julian I. Kamil

© Copyright 2025 Julian I. Kamil. All rights reserved.

License

Yokan Board MCP is available under a dual license:

  • AGPLv3: Free to use, modify, and distribute under the terms of the GNU Affero General Public License Version 3 (see LICENSE.AGPLv3)

  • Commercial License: Available for organizations that wish to use Yokan without AGPLv3's copyleft requirements (see LICENSE.COMMERCIAL)

For information on commercial use licensing, please email: yokan.board@gmail.com

Available Tools

17 tools
create_boardB

Creates a new Kanban board with an optional list of initial column names.

Args: name (str): The name of the new board. auth (AuthContext): The authentication context containing user ID and token. columns (List[str], optional): A list of names for initial columns. Defaults to an empty list.

Returns: int: The ID of the newly created board.

Inputs: name (required), auth (required), columns. Returns: result

create_columnC

Creates a new column in a specified board.

Args: board_id (int): The ID of the board to add the column to. name (str): The name of the new column. auth (AuthContext): The authentication context containing user ID and token.

Returns: yokan_models.Column: The newly created column object.

Inputs: board_id (required), name (required), auth (required). Returns: id, tasks, title, minimized, +1 more

create_taskB

Creates a new task in a specified column with optional description and due date.

Args: board_id (int): The ID of the board containing the column. column_id (str): The ID of the column to add the task to. title (str): The title of the new task. auth (AuthContext): The authentication context containing user ID and token. description (Optional[str], optional): The description of the task. Defaults to None. dueDate (Optional[str], optional): The due date of the task (e.g., "YYYY-MM-DD"). Defaults to None.

Returns: str: The ID of the newly created task.

Inputs: board_id (required), column_id (required), title (required), auth (required), +2 more. Returns: result

create_tasksB

Creates multiple new tasks in a specified column.

Args: board_id (int): The ID of the board containing the column. column_id (str): The ID of the column to add the tasks to. tasks (List[Dict]): A list of dictionaries, where each dictionary represents a task and contains 'title' and optional 'description' and 'dueDate'. auth (AuthContext): The authentication context containing user ID and token.

Returns: List[str]: A list of IDs for the newly created tasks.

Inputs: board_id (required), column_id (required), tasks (required), auth (required). Returns: result

delete_boardB

Deletes a Kanban board by its ID.

Args: board_id (int): The ID of the board to delete. auth (AuthContext): The authentication context containing user ID and token.

Returns: int: The ID of the deleted board.

Inputs: board_id (required), auth (required). Returns: result

delete_columnB

Deletes a column from a board.

Args: board_id (int): The ID of the board containing the column. column_id (str): The ID of the column to delete. auth (AuthContext): The authentication context containing user ID and token.

Returns: int: The ID of the updated board.

Inputs: board_id (required), column_id (required), auth (required). Returns: result

delete_taskC

Deletes a task from a board.

Args: board_id (int): The ID of the board containing the task. task_id (str): The ID of the task to delete. auth (AuthContext): The authentication context containing user ID and token.

Returns: None

Inputs: board_id (required), task_id (required), auth (required).

get_boardB

Retrieves a specific Kanban board by its ID.

Args: board_id (int): The ID of the board to retrieve. auth (AuthContext): The authentication context containing user ID and token.

Returns: yokan_models.Board: The requested Kanban board.

Inputs: board_id (required), auth (required). Returns: id, data, name, user_id

get_boardsA

Retrieves all Kanban boards for the authenticated user.

Args: auth (AuthContext): The authentication context containing user ID and token.

Returns: List[yokan_models.Board]: A list of Kanban boards.

Inputs: auth (required). Returns: result

get_columnsB

Retrieves all columns for a given board.

Args: board_id (int): The ID of the board to retrieve columns from. auth (AuthContext): The authentication context containing user ID and token.

Returns: List[yokan_models.Column]: A list of column objects.

Inputs: board_id (required), auth (required). Returns: result

get_tasksA

Retrieves all tasks for a given board, optionally filtered by column.

Args: board_id (int): The ID of the board to retrieve tasks from. auth (AuthContext): The authentication context containing user ID and token. column_id (Optional[str], optional): The ID of the column to filter tasks by. If None, retrieves tasks from all columns. Defaults to None.

Returns: List[Dict]: A list of dictionaries, where each dictionary represents a task.

Inputs: board_id (required), auth (required), column_id. Returns: result

move_taskC

Moves a task from one column to another.

Args: board_id (int): The ID of the board containing the task. task_id (str): The ID of the task to move. new_column_id (str): The ID of the destination column. auth (AuthContext): The authentication context containing user ID and token.

Returns: None

Inputs: board_id (required), task_id (required), new_column_id (required), auth (required).

reorder_columnsA

Reorders columns within a board.

Args: board_id (int): The ID of the board containing the columns. column_ids (List[str]): A list of column IDs in the desired new order. auth (AuthContext): The authentication context containing user ID and token.

Returns: int: The ID of the updated board.

Inputs: board_id (required), column_ids (required), auth (required). Returns: result

update_boardC

Updates the name of a Kanban board.

Args: board_id (int): The ID of the board to update. name (str): The new name for the board. auth (AuthContext): The authentication context containing user ID and token.

Returns: int: The ID of the updated board.

Inputs: board_id (required), name (required), auth (required). Returns: result

update_columnC

Updates the name of a column.

Args: board_id (int): The ID of the board containing the column. column_id (str): The ID of the column to update. name (str): The new name for the column. auth (AuthContext): The authentication context containing user ID and token.

Returns: yokan_models.Column: The updated column object.

Inputs: board_id (required), column_id (required), name (required), auth (required). Returns: id, tasks, title, minimized, +1 more

update_column_colorA

Updates the highlight color of a specified column.

Args: board_id (int): The ID of the board containing the column. column_id (str): The ID of the column to update. color (str): The new highlight color for the column (e.g., "red", "#FF0000"). auth (AuthContext): The authentication context containing user ID and token.

Returns: yokan_models.Column: The updated column object.

Inputs: board_id (required), column_id (required), color (required), auth (required). Returns: id, tasks, title, minimized, +1 more

update_taskB

Updates the title, description, due date, and/or subtasks of an existing task.

Args: board_id (int): The ID of the board containing the task. task_id (str): The ID of the task to update. auth (AuthContext): The authentication context containing user ID and token. title (Optional[str], optional): The new title for the task. Defaults to None. description (Optional[str], optional): The new description for the task. Defaults to None. dueDate (Optional[str], optional): The new due date for the task (e.g., "YYYY-MM-DD"). Defaults to None. subtasks (Optional[List[str]], optional): A list of subtask IDs. Defaults to None.

Returns: None

Inputs: board_id (required), task_id (required), auth (required), title, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 17 tools

    Disambiguation5/5

    Every tool has a distinct purpose with clear boundaries: create/read/update/delete operations for boards, columns, and tasks, plus specific actions like move_task and reorder_columns. There is no overlap or ambiguity between tools.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern (e.g., create_board, get_boards, update_task). The naming is uniform throughout with no deviations in style or convention.

    Tool Count4/5

    17 tools is slightly high but reasonable for a Kanban board system covering boards, columns, and tasks with full CRUD operations and additional features like moving and reordering. It's well-scoped without being excessive.

    Completeness5/5

    The toolset provides complete CRUD coverage for boards, columns, and tasks, including specific operations like move_task and reorder_columns. There are no obvious gaps for core Kanban functionality.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers