TaskFrame MCP Server

HTTP MCP server for TaskFrame — lets AI agents work with projects, tasks, comments and docs via the TaskFrame external API.

Each request is stateless. The Bearer token from the client is forwarded directly to TaskFrame — no credentials are stored on the server.

For humans

Requirements

• Node.js 22+

• TaskFrame API key (tf_live_...) — create one in TaskFrame → Settings → API Keys

• TASKFRAME_BASE_URL — your TaskFrame instance URL

Run locally

cp .env.example .env
# edit .env: set TASKFRAME_BASE_URL
npm install
npm run dev

Run with Docker (HTTP only — for local testing)

docker build -t taskframe-mcp .
docker run -e TASKFRAME_BASE_URL=https://your-taskframe-domain.com -p 3000:3000 taskframe-mcp

Deploy with HTTPS (docker-compose + Caddy) — recommended for production

This runs the MCP server behind Caddy, which obtains and auto-renews a free Let's Encrypt TLS certificate for you. The Node server is never exposed directly — only Caddy's 443 faces the internet.

1. Point a hostname at your server's IP. Options:

   • a real domain: mcp.example.com → your IP via an A record

   • no domain? use a free sslip.io name that encodes your IP, e.g. IP 203.0.113.10 → 203-0-113-10.sslip.io (resolves automatically)

2. Open ports 80 and 443 to the internet (80 is needed for certificate issuance).

3. Configure and launch:

cp .env.example .env
# edit .env: set TASKFRAME_BASE_URL and SITE_ADDRESS (your hostname)
docker compose up -d

Caddy fetches the certificate on the first request. Your endpoint is then https://<SITE_ADDRESS>/mcp — give that URL to clients.

Environment variables

Health check

curl http://localhost:3000/health
# → {"ok":true}

Related MCP server: plane-mcp-server

Security & deployment

Built-in protections:

• Stateless — no token, workspace id, or session is stored between requests. Each call is authenticated solely by its own Bearer header.

• ID validation — all UUID/key arguments are schema-validated and URL-encoded, so a tool argument can never alter the upstream request path (no path traversal / SSRF into other TaskFrame endpoints).

• Upstream timeout — requests to TaskFrame abort after 15s, returning 504 instead of hanging.

• Body limit — JSON bodies over 1 MB are rejected with 413.

• Scoped by the key — the server never grants more than the API key's own permissions; it cannot escalate access.

Recommended for production: run the reverse proxy with rate limiting, set ALLOWED_HOSTS to your public hostname, and keep the container non-root (the node base image already runs as a non-root node user when configured).

Connect to Claude Code

Add to your ~/.claude/settings.json (global) or .claude/settings.json (project):

{
  "mcpServers": {
    "taskframe": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer tf_live_..."
      }
    }
  }
}

Each user sets their own API key in the Authorization header. The server is shared — the key is not.

For agents

The server exposes a resource taskframe://guide that Claude Code loads automatically into context. If your client does not load resources automatically, call get_guide first.

How auth works

Pass your TaskFrame API key as Authorization: Bearer <key> in the HTTP request to this MCP server. The server resolves your workspaceId automatically via /me — never pass workspaceId as a tool argument.

Recommended flow

list_projects
  → pick projectId

get_project_meta(projectId)
  → columns[].id  → use as statusId
  → sprints[].id  → use as sprintId
  → members[].id  → use as assigneeId

list_tasks(projectId)      — read existing tasks
create_task(projectId, …)  — create new task
update_task(taskId, …)     — update fields

Key shortcuts

• Use get_task_by_key with keys like APP-43 when you have them — it's faster than get_task by UUID

• description (tasks) and content (docs/comments) accept plain text — the server wraps it in TipTap JSON automatically

• sprintId: omit → active sprint, null → backlog, UUID → specific sprint

Tools

Context

Projects

Tasks

create_task and update_task accept: description, type, priority, statusId, assigneeId, parentTaskId, estimateMinutes, storyPoints, dueDate, startDate, sprintId, labelIds.

Comments

Docs

Permissions

The server uses whatever permissions your API key has. If a tool returns a 403 error, the key needs the corresponding permission added in TaskFrame settings.

Error format

All tools return errors as text content with isError: true. The message includes the HTTP status and TaskFrame error description:

Error: 403: API key does not allow this operation
Error: 404: Task not found

Development

npm run dev    # watch mode with tsx
npm run build  # compile to dist/
npm start      # run compiled output