mcpengine/servers/asana/README.md

Asana MCP Server

A comprehensive Model Context Protocol (MCP) server for Asana, providing AI assistants with full access to Asana's project management capabilities. This server enables task management, project tracking, team collaboration, and workflow automation through 96 tools across 12 categories.

Features

• Task Management: Create, update, delete, search, and manage tasks with full support for subtasks, dependencies, and custom fields
• Project Operations: Full project lifecycle management including creation, updates, task organization, and project status tracking
• Workspace & Teams: Manage workspaces, teams, team memberships, and organizational structure
• User Management: List users, get user details, manage favorites and task lists
• Sections & Organization: Create and manage sections within projects for better task organization
• Tags & Custom Fields: Apply tags for categorization and leverage custom fields for metadata
• Goals & Portfolios: Track high-level goals and organize projects into portfolios
• Status Updates: Post and manage project status updates for stakeholder communication
• Webhooks: Set up real-time webhooks for event-driven integrations
• 16 React Apps: Pre-built UI components for task boards, project dashboards, team views, and more
• Advanced Search: Query tasks and projects with complex filters and field selections
• Rate Limiting: Built-in 150 requests/minute rate limiting with automatic retry

Installation

npm install && npm run build

Environment Variables

Variable	Required	Description	Example
ASANA_ACCESS_TOKEN	Yes	Your Asana Personal Access Token (PAT)	1/1234567890abcdef:fedcba0987654321

Getting Your Access Token

1. Log in to Asana: Go to app.asana.com
2. Open Developer Console: Click your profile photo → Settings → Apps tab
3. Create Personal Access Token:
   • Scroll to "Personal access tokens" section
   • Click + New access token
   • Enter a descriptive name (e.g., "MCP Server Integration")
   • Click Create token
4. Copy Your Token: The token will be displayed once — copy it immediately and store it securely
5. Set Environment Variable: Add to your shell profile or .env file:

   export ASANA_ACCESS_TOKEN="your_token_here"
   

Security Note: Personal Access Tokens have the same permissions as your user account. Keep them secure and never commit them to version control.

Required API Scopes

Asana Personal Access Tokens automatically inherit all permissions from your user account. The server uses these API capabilities:

• Tasks: Read, create, update, delete tasks and subtasks
• Projects: Read, create, update, delete projects
• Workspaces & Organizations: Read workspace and organization data
• Teams: Read team information and memberships
• Users: Read user profiles and task assignments
• Custom Fields: Read and write custom field values
• Tags: Create and apply tags
• Goals: Read and update goal data
• Portfolios: Read and manage portfolios
• Status Updates: Post project status updates
• Webhooks: Create and manage webhooks
• Attachments: Upload and manage file attachments

Usage

stdio Mode (Default)

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "asana": {
      "command": "node",
      "args": [
        "/path/to/mcpengine-repo/servers/asana/dist/index.js"
      ],
      "env": {
        "ASANA_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

HTTP Mode

The server can also run as an HTTP endpoint:

export ASANA_ACCESS_TOKEN="your_token_here"
npm start -- --http --port 3000

Then configure your MCP client to connect to http://localhost:3000.

Coverage Manifest

Total API endpoints: ~350 (Asana REST API v1.0)
Tools implemented: 96
Intentionally skipped: ~200 (deprecated endpoints, admin-only features, edge cases)
Not yet covered: ~54 (attachments, stories, organization exports, batch operations)
Coverage: 96/350 = 27%

Coverage Notes:

• ✅ Complete: Tasks (6 tools), Projects (8 tools), Workspaces (4 tools), Teams (8 tools), Users (8 tools), Sections (8 tools), Tags (8 tools), Goals (8 tools), Portfolios (8 tools), Custom Fields (8 tools), Status Updates (8 tools), Webhooks (8 tools)
• ⏭️ Skipped: Type-ahead autocomplete, deprecated workspace APIs, organization-level admin operations
• 🚧 Planned: Attachment management, task stories/comments, audit logs, batch operations, time tracking

Example Use Cases

• "Create a new task in the Marketing project assigned to Sarah, due next Friday"
• "List all tasks assigned to me that are due this week"
• "Update the Q1 Planning project status to 'On Track'"
• "Create a new portfolio called 'Product Initiatives' and add 3 projects to it"
• "Set up a webhook to notify when tasks are completed in the Engineering workspace"
• "Get all custom fields for the Design project"

Architecture

The server uses lazy-loaded tool modules for optimal performance:

• Client: AsanaClient with rate limiting (150 req/min)
• Tools: 12 tool modules with 96 total tools
• Apps: 16 React-based UI components
• Auth: Bearer token authentication
• Pagination: Automatic offset-based pagination for list operations

Links

• Asana API Documentation
• Asana API Explorer
• Rate Limits
• Webhooks Guide