asana-mcp

A minimal, zero-destructive MCP server for Asana — built because the official Anthropic/Asana connector is broken.

Why this exists

The official Asana connector surfaced in Claude Code as mcp__claude_ai_Asana__* tools. As of mid-2026 it stopped working — claude.ai's registry returns "Server not found" and Asana's /sse endpoint has been deprecated. There's no ETA on a fix.

Rather than wait, this is a clean TypeScript MCP server using the official asana npm SDK (v3.x) and a Personal Access Token. It gives Claude Code full Asana access with no third-party middleman, no destructive operations, and a minimal dependency footprint.

Related MCP server: MCP Server for Asana

Features

• 26 tools — 13 read, 13 write, 0 destructive (no delete operations)

• Custom field support — set enum, multi-enum, number, text, and date custom fields on create and update

• Read-only mode — set READ_ONLY_MODE=true to hide all write tools

• Minimal deps — asana SDK, zod, @modelcontextprotocol/sdk, dotenv

Tools

Requirements

• Node.js ≥ 18

• An Asana account with a Personal Access Token

Setup

1. Get an Asana PAT

Go to Asana → Settings → Developer apps → Personal access tokens and create a token.

2. Configure environment

cp .env.example .env
# Edit .env and fill in your values

.env:

ASANA_ACCESS_TOKEN=your_token_here
ASANA_WORKSPACE_ID=your_workspace_gid
ASANA_DEFAULT_PROJECT_ID=your_default_project_gid   # optional fallback
READ_ONLY_MODE=false

Finding your Workspace GID: Open Asana in a browser and navigate to any project. The URL looks like https://app.asana.com/0/<workspace_gid>/<project_gid>. The first long number after /0/ is your workspace GID. Alternatively, after setup you can call asana_list_workspaces and it will return it.

Note: Always pass project explicitly when creating tasks. If omitted, the server falls back to ASANA_DEFAULT_PROJECT_ID.

3. Build

npm install
npm run build

4. Register with Claude Code

claude mcp add asana -s user -- node /absolute/path/to/asana-mcp/dist/index.js

Or with env vars inline (if you prefer not to use a .env file):

claude mcp add asana -s user \
  -e ASANA_ACCESS_TOKEN=your_token \
  -e ASANA_WORKSPACE_ID=your_workspace_gid \
  -- node /absolute/path/to/asana-mcp/dist/index.js

Restart Claude Code, then enable via /mcp.

Custom fields

asana_create_task and asana_update_task accept a custom_fields object. Keys are custom-field GIDs; value shape depends on field type:

{
  "custom_fields": {
    "1234567890000001": "9876543210000001",
    "1234567890000002": ["9876543210000002", "9876543210000003"],
    "1234567890000003": 42,
    "1234567890000004": "plain text",
    "1234567890000005": { "date": "2026-12-31" }
  }
}

The field must be enabled on the task's project/portfolio for the API to accept it.

Development

npm run build      # tsc → dist/

After rebuilding, restart your Claude Code session — stdio MCP servers are spawned at session start and don't hot-reload.

License

UNLICENSED