Taskpile MCP

Public documentation for Taskpile's Model Context Protocol server.

Never forget a thing. Stay focused on today. Taskpile is a personal task tracker built around two verbs: pile in, sort out. Capture anything the moment it shows up, from Claude, ChatGPT or any MCP-compatible client, or in the app at taskpile.app. A two-minute daily review turns the pile into one short Today list; everything else waits its turn.

Taskpile is listed in the Claude connectors directory.

• App: https://taskpile.app

• MCP endpoint: https://taskpile.app/api/mcp

• Transport: Streamable HTTP (JSON-RPC 2.0)

• Protocol versions supported: 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05

This repository contains only public-facing documentation for the MCP integration. The Taskpile app itself is a hosted commercial product: its source isn't here, but everything you need to connect a client and use the MCP tools is.

Connecting

Any MCP-compatible client can connect by pointing at the URL above. Authentication uses OAuth 2.1 with Dynamic Client Registration + PKCE. The client handles this automatically; users sign in to Taskpile in a browser tab when prompted.

Verified clients:

Related MCP server: TaskFlow MCP Server

Quick start by client

See examples/ for ready-to-paste config snippets:

• Claude Desktop

• Cursor

• Cline (VS Code)

• MCP Inspector

For hosted clients like Claude.ai and ChatGPT, add Taskpile via their built-in connector UI and paste the URL above; no local config needed.

Tools

Taskpile exposes 72 tools spanning task CRUD, projects, tags, colors, search, bulk operations, teams, and account integrations like morning digest and task reminders. The full machine-readable schema (names, descriptions, JSON Schema for inputs and outputs) is in tools.json, generated from the server's tool schema.

tools/list is tailored to the account, so a client usually sees fewer than 72: team administration tools appear once the user belongs to a team, project-member tools once they have a shared project, assignment/triage tools once they can reach a team-owned project, and search/fetch only for OpenAI clients. Hidden tools stay callable; the entry points (create_team, convert_project_to_shared, invite_to_project, list_received_invitations, accept_invitation) are always listed.

A quick taste:

• create_task, list_tasks, update_task, complete_task, delete_task

• assign_horizon (today_morning, tomorrow, next_week, etc.), delegate_task, set_recurrence

• list_projects, create_project, archive_project

• search_tasks (free-text + status/horizon filters)

• bulk_complete, bulk_archive (reversible, prefer it over bulk_delete), bulk_delete, bulk_assign_horizon (up to 200 ids per call)

• changes_since (incremental sync: deletions are not reported, so reconcile with a full fetch periodically; capped at 500 rows per call), get_today, get_review_queue

• list_closed_tasks (what got completed in a date range)

• get_morning_digest, configure_morning_digest, get_task_reminders, configure_task_reminders

• list_colors, create_color, update_color, delete_color

• whoami, get_inbox_email

• Teams: create_team, invite_to_team, accept_invitation, assign_task, convert_project_to_shared, etc.

• search and fetch (ChatGPT Connectors built-in tools, mapped to Taskpile)

Conventions

A few project-wide conventions worth knowing if you're writing a prompt:

• Tags use @tag_name. Projects use #project_name. Do NOT use # for tags: #foo is silently treated as a project name.

• create_task parses #project and @tag shorthand from the title. Only the FIRST # token becomes the project; the rest are stripped.

• #name resolution covers projects shared with you, not just your own. If the name is unique it's used; if it's ambiguous (e.g. a private AND a shared project with the same name) the call fails with a candidate list: ask the user which, then retry with an explicit projectId. If nothing matches, a new project you own is created.

• To set tags at creation, pass tags: string[] and/or put @tag in the title. Both forms work and are de-duplicated.

• update_task does not parse #/@ shorthand from the title. Use tags / addTags / removeTags and projectId to change those.

• Prefer dedicated verbs over update_task when they exist: complete_task, assign_horizon, delegate_task.

• Bulk endpoints accept up to 200 ids per call.

Auth flow

If you're building a client and want to know what to expect:

1. Client sends an unauthenticated request to https://taskpile.app/api/mcp and receives 401 with WWW-Authenticate: Bearer realm="taskpile", resource_metadata="https://taskpile.app/.well-known/oauth-protected-resource".

2. Client fetches https://taskpile.app/.well-known/oauth-protected-resource and …/oauth-authorization-server to discover endpoints.

3. Client POSTs to https://taskpile.app/oauth/register for Dynamic Client Registration (RFC 7591).

4. Client kicks off the standard authorization-code + PKCE flow, opens a browser at /oauth/authorize, exchanges the code at /oauth/token, and receives an access_token.

5. Subsequent requests carry Authorization: Bearer <token>. Access tokens are valid for 30 days. A client that registers the refresh_token grant also gets a refresh token, valid for 90 days and rotated on every use; other clients re-run the authorize/token flow on expiry. Tokens can be revoked at /oauth/revoke (RFC 7009).

HEAD /api/mcp returns 200 without auth and is intended for liveness probes only.

Privacy + data handling

• Taskpile is GDPR-compliant. Tasks, projects, and tags created via MCP are user-owned and visible only to the authenticated user (and their team members for shared projects).

• The MCP integration sends task content to Taskpile's servers (EU-hosted). It does NOT route through Anthropic, OpenAI, or any other LLM provider: those are clients of the MCP server, not the server itself.

• Personal access tokens can be created in Taskpile → Settings → Integrations and revoked at any time.

Issues and feedback

This repo is for documentation. Bug reports about the MCP server, feature requests for new tools, or questions about the API: please open an issue here and we'll triage.

For Taskpile app issues (unrelated to MCP), please contact us through the app at https://taskpile.app.

License

Documentation in this repository is MIT-licensed (see LICENSE). The Taskpile app itself is a hosted commercial product and is not licensed for redistribution.