Wekan MCP Server

made by namar0x0309 with ❤️ at GoAIX

This project includes scripts to automatically generate Wekan API tokens and configure your environment.

Getting Started

Installation

Install dependencies and build the project:

npm install
npm run build

Generate Wekan API Token

Run the appropriate script for your platform to generate your API token:

Windows (PowerShell):

./get-wekan-token.ps1

Linux/macOS (Bash):

./get-wekan-token.sh

The script will prompt you for:

• Wekan endpoint (e.g., https://wekan.uan.com.br)
• Username (e.g., jarbas)
• Password (e.g., VN2k8bD2iKUCVCm)

After successful authentication, it will:

1. Generate an API token
2. Create or update the .env file with your token and configuration

Manual Configuration

If you prefer to configure manually, copy .env.example to .env and fill in your details:

cp .env.example .env

Then edit the .env file with your Wekan instance details and API token.

Environment Variables

The .env file contains:

• WEKAN_BASE_URL: Your Wekan instance URL
• WEKAN_API_TOKEN: Generated API token for authentication
• WEKAN_USER_ID: Your Wekan user ID
• WEKAN_TOKEN_EXPIRES: Token expiration date

Claude Code Configuration

To use this MCP server with Claude Code, you can configure it via CLI or config file.

Via CLI

claude mcp add --transport stdio wekan \
  --env WEKAN_BASE_URL="https://wekan.uan.com.br" \
  --env WEKAN_API_TOKEN="your-token" \
  --env WEKAN_USER_ID="your-user-id" \
  -- node /path/to/wekan-mcp/dist/server.js

Via config file

Add to your ~/.claude.json or .mcp.json in the project root:

{
  "mcpServers": {
    "wekan": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/wekan-mcp/dist/server.js"],
      "env": {
        "WEKAN_BASE_URL": "https://wekan.uan.com.br",
        "WEKAN_API_TOKEN": "your-token",
        "WEKAN_USER_ID": "your-user-id"
      }
    }
  }
}

Replace /path/to/wekan-mcp with the actual path where you cloned this repository.

Verify configuration

claude mcp list

Testing

You can test your configuration by running:

node test-auth.js

This will verify that your API token is working correctly.

Development

MCP Inspector

For development and debugging the MCP server, you can use the MCP Inspector:

npm run inspect

This will launch the MCP Inspector with the configuration from mcp-inspector-config.json.

For development with automatic rebuilding:

npm run inspect:watch

This will build the project and launch the inspector, automatically rebuilding when changes are detected.

Deployment on FYN Web3

This instance runs on fyn-web3 with SSH key authentication.

SSH Setup

# Generate SSH key (if not exists)
ssh-keygen -t ed25519 -f ~/.ssh/fynadmin_key -C "fynadmin@fyn-web3" -N ""

# Deploy key to fyn-web3
python3 /path/to/deploy_key.py  # Or manually copy to ~/.ssh/authorized_keys

Git Credentials

Git credentials are stored in ~/.git-credentials for the fynadmin user.

Wekan MCP Configuration

The .env file at /home/fynadmin@ad.mesh.onl/services/wekan/wekan-mcp/.env contains:

• WEKAN_BASE_URL: https://wekan.forgetyour.name
• WEKAN_API_TOKEN: Stored securely
• WEKAN_USER_ID: F6uGvfBLSeweRZMov

Service Management

The MCP server runs via mcpo:

# Check status
ps aux | grep wekan-mcp

# Restart (from wekan-mcp directory)
npm run build
pkill -f "dist/server.js"
nohup /usr/local/bin/node dist/server.js > /tmp/wekan-mcp.log 2>&1 &

Known Issues

• moveCard 500 Error: Wekan API sometimes returns 500 errors on card moves even when successful. The MCP server now ignores these errors and returns success immediately.

Available MCP Tools

This server exposes the following tools for Wekan integration:

Boards

Tool	Description
listBoards	List all boards the authenticated user is a member of. Returns board IDs and titles.
createBoard	Create a new board with title, owner, permission (private/public), and color.

Lists & Swimlanes

Tool	Description
listLists	List all lists (columns) in a board. Returns list IDs and titles.
createList	Create a new list in a board.
renameList	Rename an existing list.
archiveList	Archive a list (soft-delete). List and its cards are not permanently removed.
listSwimlanes	List swimlanes in a board.

Cards

Tool	Description
listCards	List all cards in a specific list. Returns card IDs, titles, and descriptions.
getCard	Get full details of a single card including description, labels, due date, members, etc.
createCard	Create a card with title, description, due date, members, labels, and swimlane.
archiveCard	Archive a card (soft-delete). Card is not permanently removed.
replaceCardDescription	Replace a card description. Previous description is saved as a comment.
appendCardDescription	Append text to a card existing description.
moveCard	Move a card to a different list and/or swimlane.

Comments

Tool	Description
listCardComments	List all comments on a card.
commentCard	Add a comment to a card.

Attachments

Tool	Description
getCardAttachments	List all attachments on a card. Returns IDs, filenames, MIME types, and download URLs.
getAttachment	Get metadata for a single attachment by ID, including download URL.

Labels

Tool	Description
listLabels	List all labels defined on a board.
createLabel	Create a new label on a board with name and color.
addLabelToCard	Add a label to a card by label ID.
removeLabelFromCard	Remove a label from a card by label ID.

Tool Usage Examples

List all boards

{
  "name": "listBoards",
  "arguments": {}
}

Create a card

{
  "name": "createCard",
  "arguments": {
    "boardId": "board123",
    "listId": "list456",
    "title": "My Task",
    "description": "Task details here",
    "due": "2026-12-31T23:59:59Z"
  }
}

Move a card to another list

{
  "name": "moveCard",
  "arguments": {
    "boardId": "board123",
    "currentListId": "list456",
    "cardId": "card789",
    "newListId": "list999"
  }
}

Add a label to a card

{
  "name": "addLabelToCard",
  "arguments": {
    "boardId": "board123",
    "listId": "list456",
    "cardId": "card789",
    "labelId": "label111"
  }
}