Asana Local MCP

A local, read-only MCP server for Asana. It exposes exactly six tools that query Asana through the public REST API with a personal access token, and it never sends a POST, PUT, PATCH, or DELETE request. The server does not run a cloud service, does not store a cache or index, and does not implement OAuth, webhooks, or account registration.

Contract at a glance

• GET-only data plane; no mutation endpoints, no token argument in any tool

• Six tools: list_projects, search_tasks, get_task, list_task_comments, search_comments, get_attachment

• Token is read only from the ASANA_ACCESS_TOKEN environment variable

• Attachment access links stay out of task and comment output by default

• No local writes: no files, no cache, no index

• All error messages are sanitized; tokens, headers, and ephemeral URLs never appear in tool output or logs

Requirements

• Python 3.11 or newer

• uv (the lockfile is uv.lock)

python3 --version        # 3.11+
uv --version             # install uv first if missing

Related MCP server: asana-mcp

Install and sync

Clone the repository and install all dependencies (including the dev extras used by the test suite):

uv sync --all-extras

Run the full test suite:

uv run pytest -q

Local run options

Unpublished local checkout (this repository)

Launch the server straight from the checkout. In an MCP client config, use uv --directory pointed at the checkout; do not use uvx for an unpublished package — uvx asana-local-mcp only works once the package is published to PyPI or an index:

uv --directory /Users/coffeemug/Programming/asana-local-mcp run asana-local-mcp

Editable install (development)

uv sync --all-extras
uv run asana-local-mcp

Published execution (from PyPI or an index)

uvx asana-local-mcp

All entry points resolve the same console script, asana_local_mcp.server:main, which serves the MCP protocol over stdio.

Authentication

The server reads the access token exclusively from the ASANA_ACCESS_TOKEN environment variable. Never pass the token as a tool argument: no tool accepts one, and a token in any MCP client config is a secret waiting to leak.

1. Create a personal access token in Asana (Profile > My profile settings > Apps > Personal access tokens). Scope it to attachments:read and the data-access scope your projects need; the attachment tools require attachments:read.

2. Add it to the environment of your local MCP client configuration only. Never paste the real value into this repository, a shell history, or a commit. Example claude_desktop_config.json (replace the placeholder):

{
  "mcpServers": {
    "asana-local": {
      "command": "uv",
      "args": ["--directory", "/Users/coffeemug/Programming/asana-local-mcp", "run", "asana-local-mcp"],
      "env": {"ASANA_ACCESS_TOKEN": "<local-secret>"}
    }
  }
}

If the token is missing or blank, the server exits with code 2 and logs exactly:

ASANA_ACCESS_TOKEN is missing from MCP configuration.

Optional: cap inline image bytes with ASANA_INLINE_IMAGE_MAX_BYTES (default 2097152, maximum 5242880).

Tools

All six tools are declared read_only. Every response is a structured envelope:

{
  "items": [],
  "returned_count": 0,
  "truncated": false,
  "next_cursor": null,
  "scope": {},
  "message": null
}

returned_count always equals len(items). When truncated is true, next_cursor or message explains how to continue; pass next_cursor verbatim into the next call of the same tool.

list_projects

Lists projects whose name contains text.

Input:

{
  "text": "roadmap",
  "limit": 25,
  "cursor": null
}

Output items:

{
  "items": [
    {"gid": "1234567890123", "name": "Roadmap 2026", "permalink_url": "https://app.asana.com/0/0/1234567890123", "archived": false}
  ],
  "returned_count": 1,
  "truncated": false,
  "next_cursor": null,
  "scope": {"searched_project_gids": []},
  "message": null
}

Projects are scoped to the token's accessible workspaces. list_projects first enumerates workspaces visible to the token (up to 25, across at most 5 Asana API pages), then queries each workspace's project pages with an explicit workspace parameter — the current Asana API can require one for GET /projects. Project GIDs are deduplicated across workspaces. Results may be truncated across workspace and project pages; continue with next_cursor to resume.

search_tasks

Searches tasks across up to 25 explicitly selected projects. This is the only way to find tasks: discovery never leaves the selected projects.

Input:

{
  "project_gids": ["1234567890123"],
  "text": "launch",
  "completed": false,
  "assignee_gid": null,
  "modified_after": "2026-08-01T00:00:00Z",
  "limit": 50
}

Output items are deduplicated task summaries with their selected-project memberships; a task in multiple selected projects appears once. If the result set is truncated, retry with a narrower filter or fewer projects.

get_task

Returns one task's detail fields plus normalized attachment metadata.

Input:

{
  "task_gid": "1234567890123"
}

Output items carry name, permalink_url, assignee, due_on, completed, modified_at, html_notes, text_notes, projects, parent, and attachments (metadata only — see the attachment policy).

list_task_comments

Lists comment stories for one task, newest and oldest per Asana's story order, under strict bounds.

Input:

{
  "task_gid": "1234567890123",
  "limit": 100,
  "cursor": null
}

Output items are comments with comment_gid, task_gid, text, html_text, created_at, created_by, and attachments (metadata only). Attachment metadata for comments is bounded by a shared per-call budget of 100 fetches; when that budget runs out, the envelope message says so. If the API repeats an offset, continuation stops and the envelope message explains that results may be incomplete.

search_comments

Searches comments across selected projects, task-first.

Input:

{
  "project_gids": ["1234567890123"],
  "task_text": null,
  "comment_text": "blocker",
  "task_limit": 50,
  "comment_limit": 100
}

The scope object reports searched_project_gids, candidate_task_count, and separate task_truncated / comment_truncated flags. task_limit and comment_limit exhaustion are reported independently in message.

get_attachment

Returns one attachment's safe metadata, optionally with its image rendered inline.

Input:

{
  "attachment_gid": "1234567890123",
  "include_image": false
}

Output items carry gid, name, resource_subtype, host, size, and parent. With include_image: true, a successful render adds an MCP image content block next to the metadata envelope; any rejection is reported as truncated: true with a reason in message. include_image: false never adds an image block.

Attachment policy

• Task and comment output carries metadata only. Access links (download_url, view_url, permanent_url) are omitted from task and comment attachments by default, so ephemeral URLs never leak into model context through browsing.

• get_attachment returns fresh, ephemeral access links only when you explicitly call it. Downloads may expire after a short time; re-call get_attachment for a fresh link.

• permanent_url is only reachable with a valid Asana session in the same browser, so treat it as reference metadata, not a shared link.

• view_url may not be present for every attachment.

• Attachment bytes are fetched without the bearer token, with an Accept: image/* header only.

Image policy

Inline images are opt-in and strictly bounded:

• Rendering happens only when get_attachment is called with include_image: true.

• Only Asana-hosted attachments (host: "asana") are candidates.

• Only allowlisted image MIME types render inline: image/png, image/jpeg, image/gif, image/webp.

• Default cap: 2 MiB (ASANA_INLINE_IMAGE_MAX_BYTES=2097152); hard ceiling: 5 MiB (5242880). Larger images return a truncated: true envelope with a reason message instead of bytes.

• No inline video, PDF, document, or other binary; known subtypes are rejected before any download.

• Nothing is ever written to disk: no local files, no cache, no index.

Security and privacy

• attachments:read is required for the attachment tools; tokens without that scope get safe authentication errors.

• GET-only data plane: the client and the packaged entry point contain no POST/PUT/PATCH/DELETE path; the contract tests enforce this by inspecting the client source AST and by recording every request the transport makes.

• No OAuth, webhooks, cache, index, or cloud deployment. The server is a stdio process on your machine; it stores no state between calls beyond the stateless cursors you pass back.

• No arbitrary HTML URL fetches. Attachment discovery reads only data-asana-gid attributes from Asana HTML; URLs in HTML are never dereferenced.

• No token, log, or header leakage. Tool errors, server logs, and structured envelopes are sanitized: bearer tokens become Bearer [REDACTED] and URLs become [REDACTED_URL]. Logs record only the tool name and exception class.

• .env is excluded from version control (see .gitignore), and .env.example ships an empty token declaration with no secret.

Error messages

Every failure is returned as an error envelope whose message is safe to show. The full set:

Narrowing or continuing truncated results: pass the returned next_cursor verbatim into the same tool with the same arguments to fetch the next batch; or lower limit / add filters so the request completes inside its bounds. Cursors are stateless and tied to the exact endpoint, task, and filters that produced them.

Local smoke test (manual, optional)

Never put a real credential in an automated test or a tracked file. This smoke test uses your local client configuration only.

1. Start an MCP inspector or client pointed at the server. When run from this checkout, launch it with the local command, not uvx: npx @modelcontextprotocol/inspector -- uv --directory /Users/coffeemug/Programming/asana-local-mcp run asana-local-mcp, with the token injected through the client's env block as shown under Authentication. (uvx asana-local-mcp only applies to a published package.)

2. Call list_projects with {"limit": 1} and confirm it returns an accessible project from your workspace.

3. Verify shell output, server logs, and git status / git grep show no token, no Authorization header, and no attachment URL anywhere.

Development

uv run ruff check src tests    # lint
uv run mypy src                # strict type check
uv build                       # build wheel + sdist into dist/
uv run pytest -q               # full suite (no network; mock transport only)

The suite includes tests/test_read_only_contract.py, which pins the read-only contract: no mutation methods in the client, every recorded request is GET, the README documents exactly the six tools the server exposes, the tracked files carry no real secrets or signed access URLs, error adapters strip bearer/header/URL fragments, and the whole suite passes with ASANA_ACCESS_TOKEN absent. No test makes a live Asana request.