Skip to main content
Glama
npx -y @jtalk22/asana-mcp --setup

Why this exists

Asana's official V2 MCP server is the supported hosted choice: OAuth, workspace-scoped access, consolidated task writes, and interactive confirmations in supported clients. Its tool set changes over time, so use Asana's current tools reference rather than a frozen comparison table.

Choose this server when you want a transparent local stdio process and direct REST coverage:

Need

This server's approach

Local operation

PAT + stdio. No hosted intermediary and no product telemetry.

Controlled agent surface

Mount read, write, all, or an explicit comma-list of tools.

Board and field design

Create fields and enum options, attach fields to projects, create/reorder sections, and instantiate templates.

Reliable REST edge cases

Typed custom-field values, section placement, rich task notes, start/due ordering, pagination, and bounded retry.

Large or repetitive work

Bulk loops continue past individual failures and report per-item outcomes.

Fewer agent round-trips

Morning briefs, user queues, portfolio rollups, board rollups, and inbox triage return decision-ready results.

Local diagnostics

--doctor, explicit workspace detection, generated tool reference, and release preflight.

You can use both: the official service for managed OAuth and this package for local-first REST workflows or capabilities your operating model needs. To use this package, create a Personal Access Token, run --setup, and keep the process on your machine. It talks only to app.asana.com.

Related MCP server: Asana MCP Server

Slack + Asana continuity preview

This package remains the full 75-tool, MIT-licensed local server. Nothing below is an unlock for missing tools.

The same maintainer is also building Keep the Thread, a managed continuity layer for an independent operator or two-to-five-person team that already works in Slack and Asana but does not want another dashboard. Its first cross-tool contract asks a narrower question:

Which Slack commitment is missing, incomplete, or stale in one selected Asana project?

flowchart LR
    Slack["1–5 selected Slack channels"] --> Report["continuity_asana_discrepancy_report"]
    Asana["1 selected Asana project\nincomplete tasks only"] --> Report
    Report --> Gaps["matched commitments · gaps · task drift · next reviews"]
    Gaps --> Receipt["source IDs preserved\nwrites_performed: 0"]

Choose

When it fits

This open-source package

You want local stdio, your own PAT, all 75 Asana REST tools, controlled writes, board/schema design, and no hosted intermediary.

Keep the Thread preview

You want a managed remote MCP endpoint, official connector consent, Slack-to-Asana discrepancy reporting, saved continuity contracts, or scheduled Slack delivery.

The hosted Asana connector code is live and read-only, but public OAuth activation is still staged. See the representative input/output contract, inspect the live connector status, or request a bounded deployment review. Creating, updating, completing, or deleting Asana tasks is not part of the hosted discrepancy report.

Install

1. Get a token — app.asana.com/0/my-apps → Personal access tokens → Create. Then either:

npx -y @jtalk22/asana-mcp --setup    # stores it in the macOS Keychain (or ~/.asana-mcp.json, mode 600)

or export ASANA_PAT yourself.

2. Add the server to your MCP client:

{
  "mcpServers": {
    "asana": {
      "command": "npx",
      "args": ["-y", "@jtalk22/asana-mcp"]
    }
  }
}

Claude Code one-liner: claude mcp add asana -- npx -y @jtalk22/asana-mcp

3. Verify:

npx -y @jtalk22/asana-mcp --doctor   # token → identity → workspace → tool surface, as JSON

Workspace is auto-detected when your token sees exactly one. Tokens that see several: set ASANA_WORKSPACE_GID (the doctor lists your options) or pass workspace per call.

75 tools: read, act, design

  • 26 reads — tasks, projects, sections, users, teams, tags, stories, subtasks, dependencies, attachments, statuses, portfolios, typeahead (name→GID), cross-board duplicate detection that knows a multi-homed task is not a duplicate.

  • 40 writes — create/update/complete/assign, comments, followers, tags, dependencies, memberships, section moves, dates (start_on done right), custom fields (dates wrapped, multi_enum arrays), rich notes (sanitized), attachments (100MB uploads), bulk ops, project statuses, portfolios, templates with async-job polling, and asana_set_notes_safe for boards where automations rewrite what you just wrote.

  • 6 schema/design tools — create custom fields, extend dropdowns, attach fields to projects, sections, reorder: the agent can build the board, not just fill it.

  • 3 destructive — delete_task / delete_project / delete_section refuse to run without confirm: true.

  • Local file boundary — attach_file requires confirm: true and only reads from the current directory or ASANA_MCP_FILE_ROOTS.

  • Read-only batch — batch_ops rejects every non-GET action at both schema and runtime layers.

Every tool declares MCP annotations — readOnlyHint, destructiveHint, idempotentHint, openWorldHint, titles. Clients that honor them (Claude Code does) auto-allow reads in plan mode, parallelize them safely, and gate the destructive three.

Trim the advertised surface with ASANA_MCP_TOOLS=read (30 tools), write, or a comma-list — a triage agent doesn't need delete tools in its context.

Full inputs and semantics: docs/API.md.

Composites: one call, one answer

Five tools that replace ten-call round-trips, built from running real boards daily:

  • asana_morning_brief — incomplete tasks bucketed overdue / due-today / upcoming / blocked-by-dependency, one call.

  • asana_user_queue — one person's FULL queue, paginated past the API's 100-result search cap, bucketed by due date with per-project counts. The "what is X sitting on?" call.

  • asana_portfolio_rollup — per-project health (incomplete / overdue / completed-this-week + status) across a portfolio or project list. include_archived: true catches the open tasks hiding on archived boards — every default listing skips them.

  • asana_board_rollup — one board grouped by section, any number custom field summed per section ("Deal $", "Claim $"), deadline fields checked for overdue by name — fields resolve live from the board's own settings, nothing hard-coded.

  • asana_triage_inbox — bulk-create from a triaged list (the bulk CREATE the API doesn't have), per-item overrides, continues past failures.

Honest limits

  • Asana's search API caps at 100 results with no pagination. Tools built on it say so (truncated: true) instead of pretending the tail doesn't exist; asana_user_queue and the list tools paginate past it where the REST API allows.

  • The /batch endpoint silently discards PUT bodies and GET options upstream — so this server doesn't route writes through it. asana_batch_ops exists for GET-with-default-fields only, and its description says exactly that.

  • Comment rich text (html_text on stories) is downgraded to escaped plaintext by Asana — comments here are plain text by design rather than silently ugly.

  • Date custom fields come back as full ISO timestamps; overdue math normalizes to YYYY-MM-DD before comparing (a silent all-clear bug we hit and fixed).

  • A PAT reads only its own My Tasks (others 403) — asana_user_queue uses the assignee route that works for anyone.

More in docs/TROUBLESHOOTING.md.

Security

Your PAT has the same access as your Asana login. It's read from ASANA_PAT, the macOS Keychain (asana-mcp), or ~/.asana-mcp.json (written mode 600) — never logged, never sent anywhere but api.asana.com's host. No telemetry, no phone-home; read SECURITY.md.

Development

npm ci && npm test          # 16 unit tests, no token needed
npm run doctor              # live check against your workspace
npm run api-docs            # regenerate docs/API.md from lib/tools.js

PRs welcome — see CONTRIBUTING.md. MIT.


Available Tools

75 tools
asana_add_commentA

Add a comment (story) to a task. Prefer text (plain, with real newlines; literal "\n" sequences are auto-converted) — the /stories endpoint escapes html_text into literal tags. Pass html_text only if you accept that.

Inputs: task_gid (required), text, html_text.

asana_add_dependencyB
Idempotent

Mark a task as depending on one or more other tasks (this task waits on them).

Inputs: task_gid (required), depends_on (required).

asana_add_dependentA
Idempotent

Mark one or more tasks as dependent on this task (they wait on this one).

Inputs: task_gid (required), dependent (required).

asana_add_enum_optionA

Add an option to an existing enum/multi_enum custom field (extend a dropdown without recreating the field).

Inputs: name (required), custom_field_gid (required), color, insert_after, +1 more.

asana_add_field_to_projectA
Idempotent

Attach an existing custom field to a project (addCustomFieldSetting), optionally important/positioned. Pairs with asana_create_custom_field to build a board.

Inputs: project_gid (required), custom_field_gid (required), insert_after, is_important, +1 more.

asana_add_followerB
Idempotent

Add follower(s) to a task.

Inputs: task_gid (required), followers (required).

asana_add_project_membersA
Idempotent

Add member(s) to a project (e.g. add a teammate to a new board).

Inputs: members (required), project_gid (required).

asana_add_tagA
Idempotent

Add a tag to a task.

Inputs: tag_gid (required), task_gid (required).

asana_add_to_portfolioB
Idempotent

Add a project/portfolio item to a portfolio.

Inputs: item_gid (required), portfolio_gid (required).

asana_add_to_projectA
Idempotent

Add a task to a project, optionally placing it in a specific section. Fixes: no MCP tool for addProject + section placement.

Inputs: task_gid (required), project_gid (required), section_gid.

asana_attach_fileA

Attach a local file to an Asana task. Requires confirm:true and restricts reads to the current directory or ASANA_MCP_FILE_ROOTS. Max 100MB.

Inputs: task_gid (required), file_path (required), confirm, file_name.

asana_batch_opsA

Execute up to 5 Asana API operations in a single HTTP call. ⚠ GET-with-default-fields ONLY — options (opt_fields/completed_since) + PUT data are dropped by the batch endpoint. For filtered reads use asana_search_tasks/asana_list_*; for writes use the dedicated tools.

Inputs: actions (required).

asana_batch_updateB

Update multiple task fields in a single REST call. Combines assignee, dates, custom fields, notes, name, and completion.

Inputs: task_gid (required), name, notes, due_on, +5 more.

asana_board_rollupA
Read-onlyIdempotent

COMPOSITE: roll up ONE board (project) — active tasks grouped by section, an amount custom field summed per section and in total (e.g. "Deal $", "Claim $"), an optional secondary amount, and every task whose deadline (any named date custom fields + due_on) has passed, with days overdue and WHICH field fired. Ranked by amount descending. Fields may be given by GID or by exact name (resolved live via the project's custom_field_settings, so nothing is hard-coded).

Inputs: project_gid (required), max_pages, amount_field, status_field, +3 more.

asana_bulk_move_sectionA
Idempotent

Move MANY tasks into one section in a single call (loops section addTask). Returns a per-task summary. Throughput multiplier for triaging a board column.

Inputs: task_gids (required), section_gid (required).

asana_bulk_updateA
Idempotent

Apply the SAME field changes to MANY tasks in one call (assignee, dates, completed, notes/html_notes, custom_fields). Loops PUT per task, continues past individual failures, returns a per-task summary.

Inputs: task_gids (required), notes, due_on, assignee, +4 more.

asana_complete_taskA
Idempotent

Mark a task complete (default) or incomplete (completed:false).

Inputs: task_gid (required), completed.

asana_create_custom_fieldA

Create a workspace custom field (design the board schema). resource_subtype ∈ text|number|enum|multi_enum|date|people. For enum/multi_enum pass enum_options:[{name,color?}].

Inputs: name (required), resource_subtype (required), precision, workspace, +2 more.

asana_create_portfolioC

Create a portfolio (group projects for North-Star-style tracking).

Inputs: name (required), color, workspace.

asana_create_projectA

Create a project. In an org workspace a team GID is required; otherwise the workspace default is used.

Inputs: name (required), team, color, notes, +3 more.

asana_create_project_statusC

Post a status update to a project. status_type ∈ on_track|at_risk|off_track|on_hold|complete. text required (html_text optional).

Inputs: project_gid (required), status_type (required), text, title, +2 more.

asana_create_sectionA

Create a new section in a project. Optionally position via insert_before/insert_after (section GIDs).

Inputs: name (required), project_gid (required), insert_after, insert_before.

asana_create_subtaskB

Create a subtask under a parent task.

Inputs: name (required), parent_gid (required), notes, due_on, +3 more.

asana_create_taskA

Create a general task. Provide either projects[] (workspace inferred) or it lands in the workspace default. Supports assignee, notes/html_notes, dates, followers, tags, custom_fields (dates auto-wrapped).

Inputs: name (required), tags, notes, due_on, +7 more.

asana_delete_projectA
DestructiveIdempotent

DESTRUCTIVE — permanently delete a project. Requires confirm:true (C13 gate). No-op + gate message otherwise.

Inputs: project_gid (required), confirm.

asana_delete_sectionA
DestructiveIdempotent

DESTRUCTIVE — delete a section (Asana requires it be empty, or moves its tasks out). Requires confirm:true (C13 gate).

Inputs: section_gid (required), confirm.

asana_delete_taskA
DestructiveIdempotent

DESTRUCTIVE — permanently delete (trash) a task. Requires confirm:true (C13 gate). Without confirm it is a no-op that reports the gate.

Inputs: task_gid (required), confirm.

asana_duplicate_projectA

Duplicate an existing project (clone a board with its structure). include = fields to copy (array or comma string, e.g. ["members","task_notes","task_assignee"]). Returns an async job.

Inputs: name (required), project_gid (required), team, include.

asana_duplicate_taskA

Duplicate a task (template instantiation). include = which fields to copy (array or comma string, e.g. ["notes","assignee","subtasks","dependencies"]). Returns an async job.

Inputs: name (required), task_gid (required), include.

asana_find_duplicatesA
Read-onlyIdempotent

Find TRUE duplicate tasks. Dedupes by GID FIRST — one task on N boards = multi_homed (shared membership, reported separately, NOT a dup; deleting it removes the real task from EVERY board) — then groups DISTINCT gids by name. Scan one project/section, or projects[] for cross-board. Returns {multi_homed, true_duplicate_clusters}. Read-only — reason before you delete.

Inputs: project, section, projects, max_pages, +1 more.

asana_get_custom_fieldA
Read-onlyIdempotent

Fetch one custom field by GID — type, precision, and full enum_options (name+GID) list.

Inputs: custom_field_gid (required), opt_fields.

asana_get_custom_field_settingsA
Read-onlyIdempotent

Fetch a project's custom field settings — live field GIDs, types, and enum option GIDs. Use this to derive field/option GIDs live instead of trusting hand-coded maps that drift.

Inputs: project_gid (required), limit, max_pages, opt_fields.

asana_get_jobA
Read-onlyIdempotent

Poll an async job by GID (from duplicate_task/duplicate_project/instantiate_* tools). Returns status (not_started|in_progress|succeeded|failed) and the new_task/new_project GID once done.

Inputs: job_gid (required), opt_fields.

asana_get_portfolioA
Read-onlyIdempotent

Fetch one portfolio; set include_items=true to also pull its member projects/portfolios.

Inputs: portfolio_gid (required), opt_fields, include_items.

asana_get_projectA
Read-onlyIdempotent

Fetch one project with its custom_field_settings (field GIDs + enum option GIDs) AND its sections, merged into one response.

Inputs: project_gid (required), opt_fields.

asana_get_taskA
Read-onlyIdempotent

Fetch one task with rich fields (assignee, projects, section memberships, custom fields, notes, subtask count). Override opt_fields for more/less.

Inputs: task_gid (required), opt_fields.

asana_get_userA
Read-onlyIdempotent

Fetch one user by GID (default "me" = token owner). Returns name, email, GID.

Inputs: user_gid, opt_fields.

asana_get_workspaceA
Read-onlyIdempotent

Fetch workspace metadata (name, is_organization, email_domains).

Inputs: workspace, opt_fields.

asana_instantiate_project_templateA

Create a new project from a project template (repeatable board setup). Returns an async job whose new_project holds the created project.

Inputs: name (required), project_template_gid (required), team, public.

asana_instantiate_task_templateA

Create a new task from a task template (repeatable intake/ops task). Returns an async job whose new_task holds the created task.

Inputs: name (required), task_template_gid (required).

asana_list_attachmentsA
Read-onlyIdempotent

List a task's attachments with download/permanent URLs and sizes.

Inputs: task_gid (required), limit, max_pages, opt_fields.

asana_list_dependenciesA
Read-onlyIdempotent

Return a task's dependencies (what it waits on) AND dependents (what waits on it), in one call.

Inputs: task_gid (required).

asana_list_portfoliosA
Read-onlyIdempotent

List portfolios owned by a user in the workspace. owner defaults to "me". Paginated.

Inputs: limit, owner, max_pages, workspace, +1 more.

asana_list_projectsA
Read-onlyIdempotent

List projects in the workspace (or a team). Excludes archived by default; set include_archived=true for all. Paginated.

Inputs: team, limit, max_pages, workspace, +2 more.

asana_list_project_statusesA
Read-onlyIdempotent

List a project's status updates (status_type, title, text, author). Paginated.

Inputs: project_gid (required), limit, max_pages, opt_fields.

asana_list_sectionsA
Read-onlyIdempotent

List the sections of a project (name + GID), in board order.

Inputs: project_gid (required), opt_fields.

asana_list_storiesA
Read-onlyIdempotent

List a task's stories (comments + activity log). text field holds comment bodies. Paginated.

Inputs: task_gid (required), limit, max_pages, opt_fields.

asana_list_subtasksB
Read-onlyIdempotent

List a task's subtasks with rich fields. Paginated.

Inputs: task_gid (required), limit, max_pages, opt_fields.

asana_list_tagsA
Read-onlyIdempotent

List tags in the workspace (name → GID). Paginated.

Inputs: limit, max_pages, workspace, opt_fields.

asana_list_tasksA
Read-onlyIdempotent

List tasks by project, section, tag, OR assignee (provide exactly one anchor). Paginated. assignee uses the workspace default.

Inputs: tag, limit, project, section, +5 more.

asana_list_task_templatesB
Read-onlyIdempotent

List a project's task templates (repeatable task blueprints). Paginated.

Inputs: project_gid (required), limit, max_pages, opt_fields.

asana_list_teamsA
Read-onlyIdempotent

List teams the token owner belongs to in the workspace/organization. Paginated.

Inputs: limit, max_pages, workspace, opt_fields.

asana_list_usersA
Read-onlyIdempotent

List workspace members (name → GID resolution). Paginated.

Inputs: limit, max_pages, workspace, opt_fields.

asana_list_workspace_custom_fieldsA
Read-onlyIdempotent

List ALL custom fields defined in the workspace (design discovery — find a field GID to attach to a board). Paginated.

Inputs: limit, max_pages, workspace, opt_fields.

asana_morning_briefA
Read-onlyIdempotent

COMPOSITE: one-call daily brief — incomplete tasks bucketed into overdue / due_today / upcoming (within horizon_days) + blocked (due-window tasks waiting on an incomplete dependency), with a summary count. Defaults to "me"; pass user= for a teammate or user="all" for the whole workspace. Built on the search API (caps at 100 by due date).

Inputs: user, workspace, horizon_days.

asana_move_sectionB
Idempotent

Move a task to a different section within its project. Fixes: no MCP tool for section moves.

Inputs: task_gid (required), section_gid (required).

asana_my_tasksA
Read-onlyIdempotent

List the TOKEN OWNER's My Tasks (user task list). NOTE: a personal PAT can only read its OWN My Tasks — passing another user returns 403. For other users use asana_search_tasks or asana_list_tasks with assignee=, or asana_user_queue. Paginated.

Inputs: user, limit, max_pages, workspace, +2 more.

asana_portfolio_rollupA
Read-onlyIdempotent

COMPOSITE: per-project health across a portfolio — incomplete, overdue, and completed-in-window counts + current status, sorted by overdue. Scope via projects:[gids] (best), portfolio_gid, or default to all non-archived workspace projects (capped at max_projects). One task-list call per project; caps are reported, never silent.

Inputs: projects, workspace, window_days, max_projects, +1 more.

asana_remove_field_from_projectA
Idempotent

Detach a custom field from a project (removeCustomFieldSetting). Symmetric with asana_add_field_to_project.

Inputs: project_gid (required), custom_field_gid (required).

asana_remove_followerA
Idempotent

Remove follower(s) from a task.

Inputs: task_gid (required), followers (required).

asana_remove_from_portfolioC
Idempotent

Remove an item from a portfolio.

Inputs: item_gid (required), portfolio_gid (required).

asana_remove_from_projectA
Idempotent

Remove a task from a project (un-add a board card). Symmetric with asana_add_to_project.

Inputs: task_gid (required), project_gid (required).

asana_remove_tagB
Idempotent

Remove a tag from a task.

Inputs: tag_gid (required), task_gid (required).

asana_reorder_sectionA
Idempotent

Reorder a section within its project (move a board column). Provide before_section or after_section (section GIDs).

Inputs: project_gid (required), section_gid (required), after_section, before_section.

asana_search_tasksA
Read-onlyIdempotent

Advanced workspace task search with filters: text, assignee, project, section, tag, completed, due/created date ranges, custom-field filters (filters passthrough), sorting. Single page (search API caps at 100, no offset).

Inputs: tag, text, limit, filters, +12 more.

asana_set_custom_fieldsA
Idempotent

Set custom fields on a task using correct type handling. Fixes: multi_enum arrays and date object wrappers that fail via official MCP.

Inputs: task_gid (required), custom_fields (required).

asana_set_datesA
Idempotent

Set start_on and/or due_on dates on a task. Fixes: start_on not exposed in official MCP schema, and due_on must be set first.

Inputs: task_gid (required), due_on, start_on.

asana_set_html_notesA
Idempotent

Set rich-text notes on a task using html_notes. Fixes: "XML is invalid" error from official MCP.

Inputs: task_gid (required), html_notes (required), sanitize.

asana_set_notes_safeA
Idempotent

Set notes AND survive workspace automations that rewrite the task name / parse dates out of notes text (Rules and some integrations do this): write notes, wait settle_ms, then re-assert name + due_on. Use instead of raw notes edits on automated boards.

Inputs: task_gid (required), name, notes, due_on, +2 more.

asana_set_parentA
Idempotent

Re-parent a task: make it a subtask of parent_gid, or detach to top level (parent_gid:null). Optional insert_before/insert_after sibling GIDs.

Inputs: task_gid (required), parent_gid, insert_after, insert_before.

asana_triage_inboxA

COMPOSITE: bulk-create tasks from a triaged list in ONE call (fills the gap — no bulk CREATE existed). The model reads the inbox/note, extracts items, and passes them here. Per-item project/assignee/section/due override the defaults; default_assignee falls back to ASANA_DEFAULT_ASSIGNEE, else "me". Continues past individual failures; returns a per-item created/failed summary with permalinks.

Inputs: items (required), workspace, default_project, default_section, +1 more.

asana_typeaheadA
Read-onlyIdempotent

Resolve a partial NAME → GID across the workspace for any resource type (task|project|user|tag|portfolio|project_template|goal). Fast lookup when you do not know the GID.

Inputs: query (required), count, workspace, opt_fields, +1 more.

asana_update_projectC
Idempotent

Update a project: name, notes, color, archived, public, default_view, dates.

Inputs: project_gid (required), name, color, notes, +5 more.

asana_update_sectionC
Idempotent

Rename a section.

Inputs: name (required), section_gid (required).

asana_user_queueA
Read-onlyIdempotent

COMPOSITE: one person's FULL incomplete queue — paginated (NOT capped at 100 like the search API), bucketed by due (overdue / due_today / this_week / later / no_due) with a per-project count map. Default user = "me"; pass user= for a teammate (the PAT-owner-only restriction on My Tasks does not apply — this uses /tasks?assignee=). The right call for "what is X sitting on?" and hand-off reviews.

Inputs: user, max_pages, workspace.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 75 tools

    Disambiguation4/5

    Most tools have clear, distinct purposes (e.g., create_task, get_task, list_tasks, complete_task, add_follower, remove_follower). A few pairs like asana_batch_update vs asana_bulk_update, asana_set_dates vs asana_set_notes_safe could be confused, but descriptions clarify differences. Overall, the set is well-differentiated.

    Naming Consistency5/5

    All tools follow a consistent 'asana_' prefix with verb_noun in snake_case. Verbs like create, get, list, update, delete, set, add, remove, move, complete, search, instantiate are used predictably. There are no naming outliers or mixed conventions.

    Tool Count1/5

    With 75 tools, the surface is extremely large for an MCP server. While Asana has many API endpoints, the tool count far exceeds the recommended 3-15 range and even the 25+ threshold for 'too many'. Many tools could be consolidated (e.g., batch operations, composite tools). This creates a heavy cognitive load for agents.

    Completeness4/5

    The tool set covers CRUD for tasks, projects, sections, custom fields, portfolios, and other resources, along with search, batch operations, and composite workflows. Minor gaps exist, like no direct tool to delete a custom field or update enum options aside from adding them, but most workflows are supported end-to-end.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers