Worksection Server

npm version License: MIT Node.js

MCP (Model Context Protocol) server for Worksection — a project management platform popular in Ukraine and Eastern Europe.

Lets AI assistants like Claude interact with your Worksection account through natural language: manage projects, tasks, comments, members, and tags.

---

Table of Contents

• Quick Start
• Installation
• Configuration
• Available Tools
• Authentication
• Rate Limits
• Security
• Development
• Project Structure
• License

---

Quick Start

# 1. Install
git clone https://github.com/novgorodskii/worksection-mcp-server.git
cd worksection-mcp-server
npm install && npm run build

# 2. Configure env vars
export WORKSECTION_URL=https://yourcompany.worksection.com
export WORKSECTION_API_KEY=your_api_key_here

# 3. Run
node dist/index.js

Get your API key in Worksection: Account → API → Show API key (only the account owner has access).

---

Installation

Prerequisites

• Node.js 18 or higher
• A Worksection account with admin access

From source

git clone https://github.com/novgorodskii/worksection-mcp-server.git
cd worksection-mcp-server
npm install
npm run build

Environment variables

Set these in your shell or create a .env file (see .env.example):

Variable	Description
WORKSECTION_URL	Your Worksection URL (e.g. https://yourcompany.worksection.com)
WORKSECTION_API_KEY	Admin API key from Worksection settings

---

Configuration

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "worksection": {
      "command": "node",
      "args": ["/path/to/worksection-mcp-server/dist/index.js"],
      "env": {
        "WORKSECTION_URL": "https://yourcompany.worksection.com",
        "WORKSECTION_API_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Code

claude mcp add worksection -- node /path/to/worksection-mcp-server/dist/index.js

Make sure WORKSECTION_URL and WORKSECTION_API_KEY are set in your shell environment.

Direct execution

WORKSECTION_URL=https://yourcompany.worksection.com \
WORKSECTION_API_KEY=your_key \
node dist/index.js

---

Available Tools

The server exposes 21 tools across 5 categories.

📁 Projects (7 tools)

Tool	Description
worksection_get_projects	List all projects with optional status filter
worksection_get_project	Get detailed project info
worksection_create_project	Create a new project
worksection_update_project	Update project details
worksection_archive_project	Archive a project
worksection_activate_project	Activate an archived project
worksection_get_project_folders	List project folders

✅ Tasks (8 tools)

Tool	Description
worksection_get_all_tasks	List all tasks across projects
worksection_get_tasks	List tasks in a specific project
worksection_get_task	Get detailed task info
worksection_create_task	Create a task (or subtask)
worksection_update_task	Update task details
worksection_complete_task	Mark task as done
worksection_reopen_task	Reopen a completed task
worksection_search_tasks	Search tasks by text, assignee, dates, etc.

💬 Comments (2 tools)

Tool	Description
worksection_get_comments	Get all comments on a task
worksection_post_comment	Post a comment to a task

👥 Members (2 tools)

Tool	Description
worksection_get_members	List all account members
worksection_add_project_members	Add members to a project

🏷️ Tags (2 tools)

Tool	Description
worksection_get_tags	List available tags/labels
worksection_set_task_tags	Set tags on a task

---

Authentication

This server uses the Admin Token authentication method:

• Generates an MD5 hash from query parameters + API key
• Provides full access to all account data
• Only the account owner can generate the API key

For per-user access, see the Worksection OAuth 2.0 docs.

---

Rate Limits

Worksection enforces a 1 request per second rate limit. This server handles it automatically — requests are queued with a minimum 1.1s interval, so you don't have to worry about hitting the limit.

---

Security

• 🔐 API key is read from environment variables only — never hardcoded
• ✅ All inputs validated with Zod schemas
• 🖥️ Runs locally via stdio transport — no network exposure
• 🛡️ Worksection API itself doesn't allow deletion of projects, tasks, comments, or members (safety by design)

---

Development

npm run dev    # Watch mode (auto-recompile)
npm run build  # One-time build
npm start      # Run the server

---

Project Structure

worksection-mcp-server/
├── src/
│   ├── index.ts              # Server entry point
│   ├── types.ts              # TypeScript type definitions
│   ├── constants.ts          # Shared constants
│   ├── services/
│   │   ├── client.ts         # Worksection API client (auth + rate limit)
│   │   └── formatters.ts     # Markdown formatting helpers
│   └── tools/
│       ├── projects.ts       # Project management tools
│       ├── tasks.ts          # Task management tools
│       ├── comments.ts       # Comment tools
│       ├── members.ts        # Member/team tools
│       └── tags.ts           # Tag/label tools
├── package.json
├── tsconfig.json
└── README.md

---

License

MIT

---

Made with ❤️ for the Worksection community