# Kanboard MCP Server
A Model Context Protocol (MCP) server that exposes Kanboard API functionality to Large Language Models (LLMs), enabling AI assistants to interact with Kanboard project management system.
## Features
This MCP server provides access to 60+ Kanboard API endpoints organized into the following categories:
- **Projects** (5 tools): Get all projects, get project by ID/name, project activity
- **Tasks** (11 tools): Create, read, update, delete tasks; search tasks; handle overdue tasks
- **Categories** (2 tools): Get categories for projects
- **Columns** (2 tools): Get board columns information
- **Boards** (1 tool): Get board information
- **Comments** (5 tools): Create, read, update, delete comments on tasks
- **Users** (9 tools): Get user information, current user data, dashboard, projects
- **Links** (12 tools): Create and manage task links and link types
- **Subtasks** (5 tools): Create, read, update, delete subtasks
- **Tags** (4 tools): Manage task tags
- **Files** (6 tools): Upload, download, and manage task file attachments
## Installation
### Prerequisites
- Python 3.10 or higher
- Access to a Kanboard instance with API enabled
- Kanboard API token
### Install from PyPI (Recommended)
```bash
# Install using uvx (no need to manage Python environments)
uvx kanboard-mcp
# Or install with pip
pip install kanboard-mcp
```
### Install from Source
```bash
# Clone the repository
git clone https://github.com/hoducha/kanboard-mcp.git
cd kanboard-mcp
# Install with uv
uv sync
# Or install with pip
pip install -e .
```
### Development Installation
```bash
# With uv
uv sync --all-extras
# Or with pip
pip install -e ".[dev]"
```
## Configuration
### Environment Variables
Create a `.env` file in the project root with the following variables:
```env
# Required
KANBOARD_URL=https://your-kanboard.com/jsonrpc.php
KANBOARD_API_TOKEN=your_api_token_here
# Optional
KANBOARD_USERNAME=jsonrpc
KANBOARD_VERIFY_SSL=true
KANBOARD_TIMEOUT=30
KANBOARD_MAX_RETRIES=3
KANBOARD_RETRY_DELAY=1.0
# MCP Server settings
MCP_SERVER_NAME="Kanboard MCP Server"
MCP_SERVER_VERSION="0.1.0"
DEBUG=false
```
### Getting Your API Token
1. Log into your Kanboard instance
2. Go to **Settings** → **API**
3. Generate a new API token
4. Copy the token and use it as `KANBOARD_API_TOKEN`
## Usage
### Running the Server
```bash
# Using uvx (recommended - no installation needed)
uvx kanboard-mcp
# Or using the installed command
kanboard-mcp
# Or using Python module
python -m kanboard_mcp.server
```
### MCP Client Integration
Add the server to your MCP client configuration. For Claude Desktop, add to your `claude_desktop_config.json`:
**Option 1: Using uvx (Recommended)**
```json
{
"mcpServers": {
"kanboard": {
"command": "/Users/username/.local/bin/uvx",
"args": ["kanboard-mcp"],
"env": {
"KANBOARD_URL": "https://your-kanboard.com/jsonrpc.php",
"KANBOARD_API_TOKEN": "your_api_token_here"
}
}
}
}
```
**Note**: Replace `/Users/username/.local/bin/uvx` with your actual uvx path. Find it by running `which uvx` in your terminal.
**Option 2: Using installed package**
```json
{
"mcpServers": {
"kanboard": {
"command": "kanboard-mcp",
"env": {
"KANBOARD_URL": "https://your-kanboard.com/jsonrpc.php",
"KANBOARD_API_TOKEN": "your_api_token_here"
}
}
}
}
```
### Testing the Connection
The server provides built-in tools for testing:
- `test_connection`: Test connection to Kanboard
- `get_server_info`: Get server information and capabilities
- `get_config_info`: Get current configuration (without sensitive data)
## API Tools
### Projects
- `getAllProjects()`: Get all projects
- `getProjectById(project_id)`: Get project by ID
- `getProjectByName(project_name)`: Get project by name
- `getProjectActivity(project_id)`: Get project activity
- `getProjectActivities(project_id)`: Get project activities
### Tasks
- `getAllTasks(project_id, status_id?)`: Get all tasks for a project
- `getTask(task_id)`: Get specific task
- `getTaskByReference(project_id, reference)`: Get task by reference
- `getOverdueTasks()`: Get all overdue tasks
- `getOverdueTasksByProject(project_id)`: Get overdue tasks for project
- `createTask(project_id, title, ...)`: Create new task
- `updateTask(task_id, ...)`: Update existing task
- `openTask(task_id)`: Open task
- `closeTask(task_id)`: Close task
- `removeTask(task_id)`: Delete task
- `searchTasks(project_id, query, ...)`: Search tasks
### Comments
- `createComment(task_id, content, user_id?)`: Create comment
- `getComment(comment_id)`: Get comment
- `getAllComments(task_id)`: Get all comments for task
- `updateComment(comment_id, content)`: Update comment
- `removeComment(comment_id)`: Delete comment
### And many more...
See the individual tool modules in `src/kanboard_mcp/tools/` for complete API documentation.
## Error Handling
All tools return responses in the format:
```json
{
"success": true,
"data": { ... }
}
```
Or on error:
```json
{
"success": false,
"error": "Error message"
}
```
## Development
### Project Structure
```
kanboard-mcp/
├── src/kanboard_mcp/
│ ├── __init__.py
│ ├── server.py # Main MCP server
│ ├── config.py # Configuration management
│ ├── client.py # Kanboard client wrapper
│ └── tools/ # API tool implementations
│ ├── projects.py
│ ├── tasks.py
│ ├── categories.py
│ ├── columns.py
│ ├── boards.py
│ ├── comments.py
│ ├── users.py
│ ├── links.py
│ ├── subtasks.py
│ ├── tags.py
│ └── files.py
├── pyproject.toml
└── README.md
```
### Running Tests
```bash
pytest
```
### Code Quality
```bash
# Format code
black src/
# Sort imports
isort src/
# Type checking
mypy src/
# Linting
ruff src/
```
## Troubleshooting
### Common Issues
1. **Connection Errors**: Check your `KANBOARD_URL` and ensure the API endpoint is correct
2. **Authentication Errors**: Verify your `KANBOARD_API_TOKEN` is valid
3. **SSL Errors**: Set `KANBOARD_VERIFY_SSL=false` for self-signed certificates (not recommended for production)
4. **Timeout Issues**: Increase `KANBOARD_TIMEOUT` value
### Claude Desktop Issues
**Python Command Not Found (`spawn python ENOENT`)**
If you get this error, Claude Desktop can't find the Python executable. Here are the solutions in order of preference:
1. **Use uvx (RECOMMENDED)**:
```json
{
"mcpServers": {
"kanboard": {
"command": "/Users/username/.local/bin/uvx",
"args": ["kanboard-mcp"],
"env": { ... }
}
}
}
```
2. **Use pip-installed package**:
```json
{
"mcpServers": {
"kanboard": {
"command": "kanboard-mcp",
"env": { ... }
}
}
}
```
3. **Use full Python path**:
```json
{
"mcpServers": {
"kanboard": {
"command": "/usr/local/bin/python3",
"args": ["-m", "kanboard_mcp.server"],
"env": {
"PYTHONPATH": "/path/to/site-packages",
...
}
}
}
}
```
**Benefits of uvx**:
- No need to manage Python environments
- Automatically installs and runs the latest version
- Works across different Python installations
- Simplest configuration
### Debug Mode
Enable debug mode for detailed logging:
```bash
DEBUG=true kanboard-mcp
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run code quality checks
6. Submit a pull request
## License
MIT License - see LICENSE file for details.
## Support
For issues and questions:
- Check the troubleshooting section
- Review Kanboard API documentation: https://docs.kanboard.org/v1/api/
- Open an issue on GitHub
Raw data
{
"_id": null,
"home_page": null,
"name": "kanboard-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "api, kanboard, mcp, model-context-protocol",
"author": null,
"author_email": "Ha Ho <hoducha@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/bb/34/8246c0c6054f978c1cb1e1166c19e0335651f1d425628348ecaf1e5c7c69/kanboard_mcp-0.1.1.tar.gz",
"platform": null,
"description": "# Kanboard MCP Server\n\nA Model Context Protocol (MCP) server that exposes Kanboard API functionality to Large Language Models (LLMs), enabling AI assistants to interact with Kanboard project management system.\n\n## Features\n\nThis MCP server provides access to 60+ Kanboard API endpoints organized into the following categories:\n\n- **Projects** (5 tools): Get all projects, get project by ID/name, project activity\n- **Tasks** (11 tools): Create, read, update, delete tasks; search tasks; handle overdue tasks\n- **Categories** (2 tools): Get categories for projects\n- **Columns** (2 tools): Get board columns information\n- **Boards** (1 tool): Get board information\n- **Comments** (5 tools): Create, read, update, delete comments on tasks\n- **Users** (9 tools): Get user information, current user data, dashboard, projects\n- **Links** (12 tools): Create and manage task links and link types\n- **Subtasks** (5 tools): Create, read, update, delete subtasks\n- **Tags** (4 tools): Manage task tags\n- **Files** (6 tools): Upload, download, and manage task file attachments\n\n## Installation\n\n### Prerequisites\n\n- Python 3.10 or higher\n- Access to a Kanboard instance with API enabled\n- Kanboard API token\n\n### Install from PyPI (Recommended)\n\n```bash\n# Install using uvx (no need to manage Python environments)\nuvx kanboard-mcp\n\n# Or install with pip\npip install kanboard-mcp\n```\n\n### Install from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/hoducha/kanboard-mcp.git\ncd kanboard-mcp\n\n# Install with uv\nuv sync\n\n# Or install with pip\npip install -e .\n```\n\n### Development Installation\n\n```bash\n# With uv\nuv sync --all-extras\n\n# Or with pip\npip install -e \".[dev]\"\n```\n\n## Configuration\n\n### Environment Variables\n\nCreate a `.env` file in the project root with the following variables:\n\n```env\n# Required\nKANBOARD_URL=https://your-kanboard.com/jsonrpc.php\nKANBOARD_API_TOKEN=your_api_token_here\n\n# Optional\nKANBOARD_USERNAME=jsonrpc\nKANBOARD_VERIFY_SSL=true\nKANBOARD_TIMEOUT=30\nKANBOARD_MAX_RETRIES=3\nKANBOARD_RETRY_DELAY=1.0\n\n# MCP Server settings\nMCP_SERVER_NAME=\"Kanboard MCP Server\"\nMCP_SERVER_VERSION=\"0.1.0\"\nDEBUG=false\n```\n\n### Getting Your API Token\n\n1. Log into your Kanboard instance\n2. Go to **Settings** \u2192 **API**\n3. Generate a new API token\n4. Copy the token and use it as `KANBOARD_API_TOKEN`\n\n## Usage\n\n### Running the Server\n\n```bash\n# Using uvx (recommended - no installation needed)\nuvx kanboard-mcp\n\n# Or using the installed command\nkanboard-mcp\n\n# Or using Python module\npython -m kanboard_mcp.server\n```\n\n### MCP Client Integration\n\nAdd the server to your MCP client configuration. For Claude Desktop, add to your `claude_desktop_config.json`:\n\n**Option 1: Using uvx (Recommended)**\n```json\n{\n \"mcpServers\": {\n \"kanboard\": {\n \"command\": \"/Users/username/.local/bin/uvx\",\n \"args\": [\"kanboard-mcp\"],\n \"env\": {\n \"KANBOARD_URL\": \"https://your-kanboard.com/jsonrpc.php\",\n \"KANBOARD_API_TOKEN\": \"your_api_token_here\"\n }\n }\n }\n}\n```\n\n**Note**: Replace `/Users/username/.local/bin/uvx` with your actual uvx path. Find it by running `which uvx` in your terminal.\n\n**Option 2: Using installed package**\n```json\n{\n \"mcpServers\": {\n \"kanboard\": {\n \"command\": \"kanboard-mcp\",\n \"env\": {\n \"KANBOARD_URL\": \"https://your-kanboard.com/jsonrpc.php\",\n \"KANBOARD_API_TOKEN\": \"your_api_token_here\"\n }\n }\n }\n}\n```\n\n### Testing the Connection\n\nThe server provides built-in tools for testing:\n\n- `test_connection`: Test connection to Kanboard\n- `get_server_info`: Get server information and capabilities\n- `get_config_info`: Get current configuration (without sensitive data)\n\n## API Tools\n\n### Projects\n\n- `getAllProjects()`: Get all projects\n- `getProjectById(project_id)`: Get project by ID\n- `getProjectByName(project_name)`: Get project by name\n- `getProjectActivity(project_id)`: Get project activity\n- `getProjectActivities(project_id)`: Get project activities\n\n### Tasks\n\n- `getAllTasks(project_id, status_id?)`: Get all tasks for a project\n- `getTask(task_id)`: Get specific task\n- `getTaskByReference(project_id, reference)`: Get task by reference\n- `getOverdueTasks()`: Get all overdue tasks\n- `getOverdueTasksByProject(project_id)`: Get overdue tasks for project\n- `createTask(project_id, title, ...)`: Create new task\n- `updateTask(task_id, ...)`: Update existing task\n- `openTask(task_id)`: Open task\n- `closeTask(task_id)`: Close task\n- `removeTask(task_id)`: Delete task\n- `searchTasks(project_id, query, ...)`: Search tasks\n\n### Comments\n\n- `createComment(task_id, content, user_id?)`: Create comment\n- `getComment(comment_id)`: Get comment\n- `getAllComments(task_id)`: Get all comments for task\n- `updateComment(comment_id, content)`: Update comment\n- `removeComment(comment_id)`: Delete comment\n\n### And many more...\n\nSee the individual tool modules in `src/kanboard_mcp/tools/` for complete API documentation.\n\n## Error Handling\n\nAll tools return responses in the format:\n\n```json\n{\n \"success\": true,\n \"data\": { ... }\n}\n```\n\nOr on error:\n\n```json\n{\n \"success\": false,\n \"error\": \"Error message\"\n}\n```\n\n## Development\n\n### Project Structure\n\n```\nkanboard-mcp/\n\u251c\u2500\u2500 src/kanboard_mcp/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 server.py # Main MCP server\n\u2502 \u251c\u2500\u2500 config.py # Configuration management\n\u2502 \u251c\u2500\u2500 client.py # Kanboard client wrapper\n\u2502 \u2514\u2500\u2500 tools/ # API tool implementations\n\u2502 \u251c\u2500\u2500 projects.py\n\u2502 \u251c\u2500\u2500 tasks.py\n\u2502 \u251c\u2500\u2500 categories.py\n\u2502 \u251c\u2500\u2500 columns.py\n\u2502 \u251c\u2500\u2500 boards.py\n\u2502 \u251c\u2500\u2500 comments.py\n\u2502 \u251c\u2500\u2500 users.py\n\u2502 \u251c\u2500\u2500 links.py\n\u2502 \u251c\u2500\u2500 subtasks.py\n\u2502 \u251c\u2500\u2500 tags.py\n\u2502 \u2514\u2500\u2500 files.py\n\u251c\u2500\u2500 pyproject.toml\n\u2514\u2500\u2500 README.md\n```\n\n### Running Tests\n\n```bash\npytest\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack src/\n\n# Sort imports\nisort src/\n\n# Type checking\nmypy src/\n\n# Linting\nruff src/\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Connection Errors**: Check your `KANBOARD_URL` and ensure the API endpoint is correct\n2. **Authentication Errors**: Verify your `KANBOARD_API_TOKEN` is valid\n3. **SSL Errors**: Set `KANBOARD_VERIFY_SSL=false` for self-signed certificates (not recommended for production)\n4. **Timeout Issues**: Increase `KANBOARD_TIMEOUT` value\n\n### Claude Desktop Issues\n\n**Python Command Not Found (`spawn python ENOENT`)**\n\nIf you get this error, Claude Desktop can't find the Python executable. Here are the solutions in order of preference:\n\n1. **Use uvx (RECOMMENDED)**:\n ```json\n {\n \"mcpServers\": {\n \"kanboard\": {\n \"command\": \"/Users/username/.local/bin/uvx\",\n \"args\": [\"kanboard-mcp\"],\n \"env\": { ... }\n }\n }\n }\n ```\n\n2. **Use pip-installed package**:\n ```json\n {\n \"mcpServers\": {\n \"kanboard\": {\n \"command\": \"kanboard-mcp\",\n \"env\": { ... }\n }\n }\n }\n ```\n\n3. **Use full Python path**:\n ```json\n {\n \"mcpServers\": {\n \"kanboard\": {\n \"command\": \"/usr/local/bin/python3\",\n \"args\": [\"-m\", \"kanboard_mcp.server\"],\n \"env\": {\n \"PYTHONPATH\": \"/path/to/site-packages\",\n ...\n }\n }\n }\n }\n ```\n\n**Benefits of uvx**:\n- No need to manage Python environments\n- Automatically installs and runs the latest version\n- Works across different Python installations\n- Simplest configuration\n\n### Debug Mode\n\nEnable debug mode for detailed logging:\n\n```bash\nDEBUG=true kanboard-mcp\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Run code quality checks\n6. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Support\n\nFor issues and questions:\n- Check the troubleshooting section\n- Review Kanboard API documentation: https://docs.kanboard.org/v1/api/\n- Open an issue on GitHub",
"bugtrack_url": null,
"license": "MIT",
"summary": "Model Context Protocol server for Kanboard API",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/hoducha/kanboard-mcp",
"Issues": "https://github.com/hoducha/kanboard-mcp/issues",
"Repository": "https://github.com/hoducha/kanboard-mcp"
},
"split_keywords": [
"api",
" kanboard",
" mcp",
" model-context-protocol"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c612738b5189f2aff4930c1dff28348f32c4f4b7dd673526a3baa9c6d5c1a2f6",
"md5": "6513dbab7d129c880fd8ad7859ade75a",
"sha256": "85a44384c64946d1c49dfa009a119a013037fa411d89f145f5a8aebf647f219f"
},
"downloads": -1,
"filename": "kanboard_mcp-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6513dbab7d129c880fd8ad7859ade75a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 21912,
"upload_time": "2025-07-18T14:30:34",
"upload_time_iso_8601": "2025-07-18T14:30:34.882670Z",
"url": "https://files.pythonhosted.org/packages/c6/12/738b5189f2aff4930c1dff28348f32c4f4b7dd673526a3baa9c6d5c1a2f6/kanboard_mcp-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bb348246c0c6054f978c1cb1e1166c19e0335651f1d425628348ecaf1e5c7c69",
"md5": "8f4259ae681c081e60c0a7a0291fde56",
"sha256": "36929ebae5c8d59cf879162cfe5ce6b97b7ed95ee243beec429260a43c8f6423"
},
"downloads": -1,
"filename": "kanboard_mcp-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "8f4259ae681c081e60c0a7a0291fde56",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 61763,
"upload_time": "2025-07-18T14:30:38",
"upload_time_iso_8601": "2025-07-18T14:30:38.248248Z",
"url": "https://files.pythonhosted.org/packages/bb/34/8246c0c6054f978c1cb1e1166c19e0335651f1d425628348ecaf1e5c7c69/kanboard_mcp-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-18 14:30:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hoducha",
"github_project": "kanboard-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "kanboard-mcp"
}
JSON
