Another Planka MCP

A Model Context Protocol (MCP) server that enables AI Chat clients to read and update your Planka boards using the Planka REST API.

Overview

Another Planka MCP Server provides you with a lightweight bridge between MCP clients and your self‑hosted Planka instance. It exposes projects, boards, lists, cards, tasks, and labels through MCP tools, allowing assistants to retrieve workspace data and perform write operations such as creating or updating cards.

Features

• List projects, boards, lists, labels, and members.
• Search and retrieve cards with multiple detail levels.
• Create and update cards (title, description, labels, tasks).
• Move cards between lists.
• Efficient token usage through structured MCP tools.
• Works with Claude Desktop, Claude.ai, and any MCP‑compatible client.
• Remote access via streamable-http transport and Docker deployment.

Example use cases:

• “Show all ‘In Progress’ cards across my workspace.”
• “Create a new card in <Board> / TODO with subtasks…”
• “Find the ‘Login bug’ card and list all tasks.”

Prerequisites

• Python 3.10+
• Access to a Planka instance
• Planka API credentials (see below)

Obtaining API Credentials

Generate a JWT access token by authenticating via API:

curl -X POST https://your-planka-instance.com/api/access-tokens \
  -H "Content-Type: application/json" \
  -d '{
    "emailOrUsername": "your-email@example.com",
    "password": "your-password"
  }'

Response:

{
  "item": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Copy the accessToken value and use it as PLANKA_API_TOKEN in your .env file.

Note: JWT tokens may expire. If you get authentication errors, generate a new token.

Email/Password (Fallback)

Use your Planka login credentials directly. The MCP server will authenticate automatically at startup:

PLANKA_EMAIL=your-email@example.com
PLANKA_PASSWORD=your-password

User Requirements:

• Any registered Planka user can authenticate
• No special permissions or admin role required
• API access permissions match your Planka user permissions
• Admin users have full access; regular users can only access boards they're members of

Setup

1. Clone the repo:

   git clone https://github.com/roelven/another-planka-mcp
   cd another-planka-mcp
   

2. Create environment:

   python -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   

3. Copy env file:

   cp .env.example .env
   

4. Fill in:

   • PLANKA_BASE_URL
   • PLANKA_API_TOKEN (recommended)

5. Start the server:

   python mcp_server.py

6. Add to Claude Desktop config:

   {
     "mcpServers": {
       "planka": {
         "command": "/absolute/path/to/venv/bin/python",
         "args": ["mcp_server.py"],
         "env": {
           "PLANKA_BASE_URL": "https://your.domain",
           "PLANKA_API_TOKEN": "<token>"
         }
       }
     }
   }

Remote Deployment (Docker)

To make the MCP server available remotely (e.g. for Claude.ai), you can deploy it with Docker using the streamable-http transport.

1. Clone the repo on your server:

   git clone https://github.com/roelven/another-planka-mcp
   cd another-planka-mcp

2. Create a .env file with your Planka credentials:

   cp .env.example .env
   # Edit .env with PLANKA_BASE_URL and PLANKA_API_TOKEN

3. Start the container:

   docker compose up -d --build

4. The MCP server is now running on port 8000 with the streamable-http transport. Expose it via a reverse proxy or Cloudflare tunnel, then add it as a remote MCP server in Claude.ai using your server's URL.

The MCP_TRANSPORT environment variable controls the transport mode:

• stdio (default) — for local MCP clients like Claude Desktop
• streamable-http — for remote access over HTTP

Tools & Capabilities

Tool	Type	Purpose
planka_get_workspace	Read	Retrieve boards, lists, users, labels
planka_list_cards	Read	Filter and list cards with detail levels
planka_find_and_get_card	Read	Search and fetch a specific card
planka_create_card	Write	Create a new card
planka_update_card	Write	Update an existing card

Usage Examples

Ask your assistant:

• “List all my boards.”
• “Search for cards mentioning ‘invoice’.”
• “Create a card named ‘App release checklist’ with these subtasks…”
• “Move the ‘Integrate payment API’ card to ‘Done’.”

Security & Permissions

• The MCP server accesses only what the authenticated Planka user can access.
• API token recommended over email/password.
• Use HTTPS when exposing Planka externally.
• Consider using a dedicated Planka service user with restricted permissions.

Troubleshooting & FAQ

401 Unauthorized
Check token validity and .env configuration.

Client cannot connect to server
Verify:

• correct Python path
• firewall rules
• execution permissions

No boards or cards returned
Confirm the Planka user has workspace access.

Development Notes

Editable Installation: This project uses an editable installation (via pip install -e . or the equivalent in the virtual environment), which means the src directory is automatically added to your Python path. This eliminates the need to manually set PYTHONPATH when running tests or the server.

Setting up editable mode: If you need to reinstall the package in editable mode, you can run:

pip install -e .

This creates a .pth file in your virtual environment that points to the src directory, making all imports work seamlessly.

Running Tests

The project includes a comprehensive test suite with >90% code coverage.

Since the package is installed in editable mode, you can run tests directly without setting PYTHONPATH:

# Install test dependencies
pip install -r requirements.txt

# Run all tests
pytest --cov=src/planka_mcp --cov-report=term-missing

# Run specific test file
pytest tests/test_cards.py -v

# View coverage report
open htmlcov/index.html

Alternatively, you can use the virtual environment's pytest directly:

venv/bin/pytest --cov=src/planka_mcp --cov-report=term-missing

Test with MCP Inspector

npx @modelcontextprotocol/inspector python mcp_server.py

Acknowledgements

• Planka project: https://github.com/plankanban/planka
• Model Context Protocol: https://modelcontextprotocol.io/

License

MIT License. See LICENSE.