@duytnb79/asana-mcp

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

It runs over stdio and calls 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.

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"

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

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.

Write tools

• create_task
  • Creates a task or subtask.
  • Requires at least one of workspace, projects, or parent.
• update_task
  • Updates fields on an existing task.
• add_comment
  • Adds a plain-text comment to a task.

Write tools make immediate changes in Asana. Configure your MCP client to require approval for these tools if you want a human confirmation step.

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, but does not automatically retry write requests because retries could duplicate creations or comments.
• 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.
• Tool calls run with the permissions of the token owner.
• This server intentionally exposes specific Asana operations rather than a generic HTTP passthrough tool.

Development

npm run dev
npm run typecheck
npm run build
npm start