@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.

Related MCP server: Asana MCP Server

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