Yokan Board MCP

<p align="center"> <img src="./images/avatar.png" alt="Yokan Logo" width="150" style="border-radius: 50%;"> </p>

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.

Tech Stack

• Python
• FastAPI
• Pydantic
• fastmcp

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.

Copyright

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