@duytnb79/asana-mcp

A read-only local MCP server for Asana that uses an Asana personal access token (PAT).

It runs over stdio and calls GET endpoints in the standard Asana REST API at https://app.asana.com/api/1.0. It is separate from Asana's hosted MCP server at https://mcp.asana.com/v2/mcp, which requires a registered MCP app and OAuth.

Requirements

• Node.js 24+

• An Asana personal access token

• Access to the Asana workspaces, projects, and tasks you want to use

Create a PAT in the Asana developer console and treat it like a password. The server can only access data and perform actions allowed for the Asana user who owns the token.

Related MCP server: asana-mcp

Installation

Local clone

npm install
npm run build
cp .env.example .env
node dist/index.js

Published package

After this package is published, it can be run with:

npx -y @duytnb79/asana-mcp

Or installed globally:

npm install -g @duytnb79/asana-mcp
asana-mcp

Configuration

Create a .env file or provide environment variables through your MCP client:

ASANA_ACCESS_TOKEN="your_asana_personal_access_token"
ASANA_TIMEOUT_MS="10000"
ASANA_MAX_PAGE_SIZE="100"
ASANA_MAX_IMAGE_BYTES="10485760"

Required:

• ASANA_ACCESS_TOKEN

Optional:

• ASANA_TIMEOUT_MS — request timeout in milliseconds; defaults to 10000

• ASANA_MAX_PAGE_SIZE — maximum page size exposed by list/search tools; defaults to 100 and must be between 1 and 100

• ASANA_MAX_IMAGE_BYTES — maximum downloaded image size in bytes; defaults to 10485760 (10 MiB)

The server automatically loads .env when running locally.

Test the Asana connection

Copy the example environment file, replace the placeholder with your real PAT, then run the read-only connection test:

cp .env.example .env
# Edit .env and set ASANA_ACCESS_TOKEN
npm run test:connection

A successful response starts with:

Asana connection successful.

It then prints the authenticated user and accessible workspaces. This test calls only GET /users/me; it does not create or modify Asana data.

MCP client configuration

Local build

{
  "mcpServers": {
    "asana": {
      "command": "node",
      "args": [
        "/absolute/path/to/asana-mcp-server/dist/index.js"
      ],
      "env": {
        "ASANA_ACCESS_TOKEN": "your_asana_personal_access_token"
      }
    }
  }
}

Alternatively, run through npm from the project directory:

{
  "mcpServers": {
    "asana": {
      "command": "npm",
      "args": ["start"],
      "cwd": "/absolute/path/to/asana-mcp-server",
      "env": {
        "ASANA_ACCESS_TOKEN": "your_asana_personal_access_token"
      }
    }
  }
}

Published package

{
  "mcpServers": {
    "asana": {
      "command": "npx",
      "args": ["-y", "@duytnb79/asana-mcp"],
      "env": {
        "ASANA_ACCESS_TOKEN": "your_asana_personal_access_token"
      }
    }
  }
}

Available tools

Read tools

• list_projects

  • Lists projects in a workspace.

  • Supports archived, limit, offset, and opt_fields.

• list_tasks

  • Lists tasks in a project in project priority order.

  • Supports completed_since, limit, offset, and opt_fields.

• get_task

  • Gets one task by GID.

• search_tasks

  • Searches a workspace by assignee, completion state, modified time, project, or text.

  • Asana search is eventually consistent and may lag recent writes by 10–60 seconds.

  • The search endpoint does not support normal Asana offset pagination and returns at most 100 items.

• list_sections

  • Lists sections in a project.

  • Supports limit, offset, and opt_fields.

• list_task_comments

  • Returns the newest human comments from one task, excluding assignment, due-date, and other system activity stories.

  • Accepts task_gid and an optional limit from 1 to 100; the default is 20.

  • Scans the task's paginated story history, filters comments, and returns the requested number in newest-first order.

• list_task_attachments

  • Lists attachment metadata for a task with offset pagination; temporary download URLs are not exposed.

• read_attachment_image

  • Downloads one attachment by GID and returns MCP image content for visual analysis.

  • Supports PNG, JPEG, WebP, and GIF up to ASANA_MAX_IMAGE_BYTES; SVG and non-image files are rejected.

The server does not register task creation, task update, or comment-writing tools. Its Asana client issues GET requests only.

Pagination

Asana list endpoints return an opaque next_page.offset. The MCP response exposes it as meta.next_offset.

Pass that value back as offset to retrieve the next page. Only use offsets returned by Asana; they can expire when underlying data changes.

Input/output fields

Asana returns compact objects by default. Use opt_fields to request additional properties, for example:

{
  "project_gid": "12345",
  "limit": 50,
  "opt_fields": [
    "name",
    "completed",
    "assignee.name",
    "due_on",
    "permalink_url"
  ]
}

Keep opt_fields focused. Very broad or deeply nested responses are more expensive and may be rate-limited.

Rate limits and errors

• Asana returns HTTP 429 when a token is rate-limited.

• The server reports the Retry-After value when Asana provides it and does not retry requests automatically.

• Authentication, permission, validation, not-found, timeout, and server errors are converted into readable MCP errors.

• The PAT is sent only in the Authorization: Bearer header and is never placed in request URLs.

Security

• Never commit .env or a PAT.

• Prefer a dedicated PAT with the minimum user permissions needed for this integration.

• Rotate the PAT if it is exposed.

• The PAT still inherits the permissions of its Asana account; read-only behavior is enforced by this server's GET-only client and exposed tools, not by changing the PAT itself.

• This server intentionally exposes specific read operations rather than a generic HTTP passthrough tool.

• Image downloads never receive the Asana authorization header, validate redirects, reject local/private IP literals, verify image signatures, and enforce a bounded in-memory size.

Development

npm run dev
npm run typecheck
npm run build
npm start