roelven/another-planka-mcp

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 and any MCP‑compatible client.

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 planka_mcp.py
   

   Note: For direct MCP protocol communication (recommended for Claude Desktop), you can also run:

   python mcp_server.py
   

   This provides better compatibility with MCP clients and includes proper protocol handling.

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>"
         }
       }
     }
   }
   

   Note: Updated to use mcp_server.py for better MCP protocol compatibility.

Tools & Capabilities

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 planka_mcp.py

Run directly

python planka_mcp.py

Acknowledgements

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

License

MIT License. See LICENSE.