Repository avatar
Other Tools
v0.2.0
active

kanboard-mcp-server

io.github.b-ak/kanboard-mcp-server

Connect Claude to a self-hosted Kanboard board to manage tasks

Documentation

Kanboard MCP Server

M8ven Score

An MCP server that lets Claude create, update and track tasks on your self-hosted Kanboard, from Claude Code, Claude Desktop, claude.ai or the Claude mobile apps.

It talks to Kanboard only through its JSON-RPC API, so it works with any Kanboard instance you can reach over HTTP (localhost, LAN or a public URL) and with any Kanboard database backend.

Tools

ToolWhat it does
list_projectsProjects with IDs and board links
get_boardColumns of a project with their open tasks
list_tasksTasks in a project, filtered by open / closed / all and column
search_tasksKanboard filter syntax (assignee:me status:open due:<=today), one or all projects
get_overdue_tasksOverdue tasks, for you or for one project
get_taskDetails, tags, subtasks, comments and attachment list
get_task_fileRead an attachment: images come back as images, text files as text
create_task / update_taskTitle, description, priority, column, assignee, due date, tags
move_taskMove a task to another column (by name)
close_task / reopen_taskComplete or reopen
add_commentAdd a progress note (Markdown)
create_subtask / update_subtaskChecklist items and their status
list_project_usersAssignable users
get_meWhich Kanboard user and API mode the server is using

Read-only tools are annotated as such, so Claude clients can auto-approve them and ask before writes.

1. Get a Kanboard API token

You can use either kind of token:

  • Personal access token (recommended): Kanboard → My profile → API → generate a token. Set KANBOARD_USERNAME to your login name. Actions run as you and follow your project permissions.
  • Application token: Kanboard → Settings → API. Set KANBOARD_USERNAME=jsonrpc. It has full access to every project. Set KANBOARD_DEFAULT_USER_ID so comments have an author.

The two are easy to mix up: the application token used with your own username fails with 401 Unauthorized.

Also set Kanboard's Settings → Application settings → Application URL to the address you open Kanboard at; otherwise the task links Claude shows you point to http://localhost/....

2. Use it from Claude Code on the same machine (stdio)

No clone needed. uv fetches and runs the server:

claude mcp add --scope user kanboard \
  --env KANBOARD_URL=http://localhost:8080 \
  --env KANBOARD_USERNAME=your-username \
  --env KANBOARD_API_TOKEN=your-token \
  -- uvx --from git+https://github.com/b-ak/kanboard-mcp-server kanboard-mcp

--scope user makes the server available in every project; without it, it is registered for the current folder only.

Claude Desktop's claude_desktop_config.json takes the same command:

{
  "mcpServers": {
    "kanboard": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/b-ak/kanboard-mcp-server", "kanboard-mcp"],
      "env": {
        "KANBOARD_URL": "http://localhost:8080",
        "KANBOARD_USERNAME": "your-username",
        "KANBOARD_API_TOKEN": "your-token"
      }
    }
  }
}

3. Use it from claude.ai and the Claude mobile apps (remote HTTP)

claude.ai and the mobile apps connect from Anthropic's cloud, so the server must:

  1. run where it can reach Kanboard (e.g. on the same Raspberry Pi),
  2. be reachable at a public HTTPS URL (Cloudflare Tunnel, Tailscale Funnel or a reverse proxy),
  3. require login. GitHub OAuth is built in and limited to the GitHub accounts you list.
Claude (web / mobile / Code) ──HTTPS──▶ tunnel/proxy ──▶ kanboard-mcp :8000 ──▶ Kanboard

docs/deployment.md walks through the whole setup step by step: Kanboard token, GitHub OAuth App, Docker Compose, Cloudflare Tunnel, connecting Claude, verification and troubleshooting.

Once it's running at https://kanboard-mcp.example.com:

  • claude.ai / mobile: Settings → Connectors → Add custom connector, URL https://kanboard-mcp.example.com/mcp, then sign in with GitHub. Connectors you add on claude.ai are also available in the Claude mobile apps.
  • Claude Code: claude mcp add --scope user --transport http kanboard https://kanboard-mcp.example.com/mcp, then run /mcp to sign in.

4. Tell Claude when to use it

Connecting gives Claude the tools, not the habits. Put your rules (which project, when to create, move, comment or close tasks, what to ask first) in your project's CLAUDE.md or a claude.ai Project's instructions. Start from docs/claude-md-template.md.

Configuration

All settings are environment variables. See .env.example. The CLI also accepts --env-file, --transport, --host and --port.

VariableDefaultDescription
KANBOARD_URLrequiredKanboard base URL; /jsonrpc.php is appended if missing
KANBOARD_USERNAMEjsonrpcYour username (personal token) or jsonrpc (application token)
KANBOARD_API_TOKENrequiredAPI token
KANBOARD_DEFAULT_USER_IDComment author when using the application token
KANBOARD_VERIFY_SSLtrueSet false for self-signed certificates
KANBOARD_TIMEOUT20Request timeout in seconds
MCP_TRANSPORTstdiostdio or http
MCP_HOST / MCP_PORT127.0.0.1 / 8000HTTP bind address (Docker image uses 0.0.0.0)
MCP_AUTHnonenone, bearer or github
MCP_BEARER_TOKENShared secret for bearer (32+ chars)
MCP_BASE_URLPublic URL of this server, for github
GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRETGitHub OAuth app credentials
MCP_ALLOWED_GITHUB_USERSComma-separated GitHub logins allowed to connect
MCP_JWT_SIGNING_KEYderivedOptional key for tokens the server issues
FASTMCP_HOME~/.local/share/fastmcpWhere OAuth state is stored (/data in Docker)

The server refuses to serve HTTP on a non-loopback address without authentication, unless you set MCP_ALLOW_UNAUTHENTICATED=true because a proxy in front of it already handles auth.

Development

uv sync
uv run pytest
uv run ruff check . && uv run ruff format --check .
uv run kanboard-mcp --env-file .env                      # stdio
uv run kanboard-mcp --env-file .env --transport http     # http on 127.0.0.1:8000
npx @modelcontextprotocol/inspector                      # optional: browse the tools

License

Apache-2.0

OCI
ghcr.io/b-ak/kanboard-mcp-server:0.2.0
Install Command
docker pull ghcr.io/b-ak/kanboard-mcp-server:0.2.0:undefined