worklenz-mcp 📋

FastMCP wrapper for Worklenz CE — 111 project management tools exposed via MCP for AI-driven task and time tracking.

---

✨ Overview

worklenz-mcp is a Python FastMCP server that wraps the Worklenz CE v2.1.6 REST API, making all project management operations available as MCP tools. It authenticates via session cookie (auto-managed), exposes three MCP sub-servers (core, time, function) on separate ports, and connects directly to the Worklenz Express backend on the internal Docker network. All 111 tools are registered in MetaMCP under the g1-project namespace.

🏗️ Architecture

graph TD
    A[Claude Code / Claude Desktop] -->|MCP g1-project namespace| B[MetaMCP<br/>mcp.generate.one]
    B -->|port 8000| C[pm-app-core<br/>Task & project CRUD]
    B -->|port 8001| D[pm-app-time<br/>Time logging & timers]
    B -->|port 8002| E[pm-app-function<br/>Reports & analytics]
    C --> F[Worklenz Backend<br/>pm.generate.one:3000]
    D --> F
    E --> F
    F --> G[PostgreSQL<br/>svc-infra]

📦 Services

Container	Port	MCP Namespace	Tool Count	Description
worklenz-mcp	8000	pm-app-core	~60	Projects, tasks, statuses, labels, phases, members, comments, attachments
worklenz-mcp	8001	pm-app-time	~10	Time logs, running timers, time summaries
worklenz-mcp	8002	pm-app-function	~41	Reports, insights, overviews, templates, allocations

All three ports run from the same container (worklenz-mcp) via the single docker-compose.yml.

🚀 Quick Start

# Build and run locally
git clone https://git.generate.one/generate-one/worklenz-mcp.git
cd worklenz-mcp

cp .env.example .env
# Edit .env with your Worklenz credentials

docker compose up -d

# Verify all three ports are live
python -c "import socket; s=socket.socket(); s.connect(('localhost',8000)); s.close(); print('core ok')"
python -c "import socket; s=socket.socket(); s.connect(('localhost',8001)); s.close(); print('time ok')"
python -c "import socket; s=socket.socket(); s.connect(('localhost',8002)); s.close(); print('func ok')"

🔧 Configuration

Variable	Description	Default
WORKLENZ_URL	Worklenz backend URL	http://backend-ocoo8o4gcw8k84cgo0oo4kc4:3000
WORKLENZ_EMAIL	Admin email for session auth	admin@generate.one
WORKLENZ_PASSWORD	Admin password	—
WORKLENZ_ORIGIN	Origin header for CSRF	https://pm.generate.one
MCP_HOST	FastMCP listen address	0.0.0.0
CORE_PORT	pm-app-core port	8000
TIME_PORT	pm-app-time port	8001
FUNC_PORT	pm-app-function port	8002

📊 Tool Categories

pm-app-core (projects, tasks, workflow)

Category	Tools	Examples
Projects	6	list_projects, get_project, create_project, update_project, delete_project
Tasks	12	list_tasks, get_task, create_task, update_task, delete_task, search_tasks
Bulk ops	5	bulk_update_task_status, bulk_update_task_priority, bulk_delete_tasks, bulk_assign_members
Statuses	6	list_task_statuses, create_task_status, update_task_status_name, delete_task_status
Labels	4	list_labels, get_task_labels, update_label, delete_label
Phases	5	list_phases, create_phase, update_phase, delete_phase
Members	5	list_team_members, list_project_members, add_project_member, remove_project_member
Comments	3	list_task_comments, create_task_comment
Dependencies	3	list_task_dependencies, create_task_dependency, delete_task_dependency
Custom cols	4	list_custom_columns, create_custom_column, set_column_value

pm-app-time (time tracking)

Tool	Description
log_time	Log seconds against a task
log_time_hours	Log hours + minutes against a task
list_time_logs	List time entries for a task
update_time_log	Edit a time log entry
delete_time_log	Delete a time log entry
get_running_timers	List all active timers
get_task_total_time	Total logged time for a task
get_time_log_summary	Summary across tasks/members
export_time_logs	Export time data

pm-app-function (reports & analytics)

Tool	Description
get_project_overview_report	Full project health overview
get_insights_status_overview	Task counts by status
get_insights_priority_overview	Task counts by priority
get_insights_overdue_tasks	Overdue task listing
get_member_overview	Member workload summary
get_allocation	Team allocation across projects
get_actual_vs_estimate	Time accuracy reporting
list_project_templates	Available project templates
create_project_from_template	Spin up from template

🔗 Dependencies

Depends on:

• g1-project — Worklenz CE backend at pm.generate.one
• svc-tools — MetaMCP registers the g1-project namespace pointing to this service

Docker Networks:

• ocoo8o4gcw8k84cgo0oo4kc4 — Worklenz internal network (backend reachability)
• a408gckoogkg440o0wkgwsgg — MetaMCP network
• coolify — Cross-stack backbone

📄 Implementation Notes

• Authentication uses session cookies (not API keys). The WorklenzClient class auto-logs in on first request and re-authenticates on 401.
• Three separate FastMCP instances share one container, each on its own port.
• server.py — core tools | pm_app_core.py — core module | pm_app_time.py — time module | pm_app_function.py — function module
• Coolify service UUID: kp3basi7wsdztrq1fgm7t543 (g1-brain project)

🔗 Related Repos

Repo	Relationship
svc-tools	MetaMCP registers g1-project namespace
g1-project	Worklenz CE backend
g1-shared	Shared playbook and conventions

---

🛡️ Part of Generate One

Generate One — AI infrastructure that answers to you.

Self-hosted, sovereign AI platform. generate.one