Provides comprehensive project management capabilities including workspace and project management, task lifecycle operations, team collaboration features, section organization, tag categorization, portfolio tracking, and search functionality across Asana's work management platform.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Asana MCP Serverlist my active projects in the marketing workspace"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Asana MCP Server
MCP server for Asana API. Complete work management platform for task tracking, project planning, team collaboration, and workflow automation. Organize work across workspaces, projects, sections, and tasks.
Features
Workspace Management: Access multiple workspaces and organizations
Project Planning: Create and manage projects with timelines
Task Management: Full task lifecycle from creation to completion
Sections: Organize tasks within projects using sections
Tags: Flexible categorization across projects
Portfolios: Group and track multiple projects
Collaboration: Assignees, followers, and comments
Custom Fields: Add metadata to tasks and projects
Search: Find tasks, projects, and users quickly
Team Coordination: Share work and track progress
Setup
Prerequisites
Asana account (free or paid plan)
Personal Access Token
Environment Variables
ASANA_PERSONAL_ACCESS_TOKEN(required): Your Asana Personal Access Token
How to get credentials:
Go to app.asana.com/0/my-apps
Sign in to your Asana account
Click on "My Profile Settings" in the top right
Select the "Apps" tab
Scroll to "Personal access tokens"
Click "Create new token"
Enter a token name (e.g., "MCP Server")
Click "Create token"
Copy the token immediately (it won't be shown again)
Store as
ASANA_PERSONAL_ACCESS_TOKEN
Token Format:
Format:
0/1234567890abcdef...Full access to your account
Keep secure - treat like a password
Rate Limits
Standard Rate Limits:
1,500 requests per minute per token
150 concurrent requests
Burst capacity for short spikes
Premium Plans:
Higher rate limits available
Contact Asana for enterprise limits
Best Practices:
Use pagination for large result sets
Cache data when appropriate
Implement exponential backoff
Monitor rate limit headers
Asana Hierarchy
Asana organizes work in this hierarchy:
Workspace/Organization
└── Project
└── Section
└── Task
└── SubtaskWorkspace: Top-level container for teams
Project: Collection of tasks for a goal
Section: Organize tasks within projects
Task: Individual work item
Subtask: Break down tasks into smaller steps
Available Tools
Workspace Management
list_workspaces
List all workspaces you have access to.
Parameters:
limit(int, optional): Results per page (default: 20, max: 100)opt_fields(string, optional): Comma-separated fields to include
Example:
workspaces = await list_workspaces(limit=20)
# With specific fields
workspaces = await list_workspaces(
limit=10,
opt_fields="name,is_organization"
)
# Returns:
# {
# "data": [
# {
# "gid": "1234567890",
# "name": "My Company",
# "resource_type": "workspace",
# "is_organization": true
# }
# ]
# }Project Management
list_projects
List projects in a workspace.
Parameters:
workspace(string, required): Workspace GIDarchived(bool, optional): Include archived projects (default: false)limit(int, optional): Results per page (default: 20, max: 100)opt_fields(string, optional): Comma-separated fields to include
Example:
# Active projects
projects = await list_projects(workspace="1234567890")
# Include archived
projects = await list_projects(
workspace="1234567890",
archived=True
)
# With specific fields
projects = await list_projects(
workspace="1234567890",
opt_fields="name,due_date,owner,color"
)
# Returns:
# {
# "data": [
# {
# "gid": "9876543210",
# "name": "Website Redesign",
# "resource_type": "project"
# }
# ]
# }get_project
Get detailed information about a project.
Parameters:
project_gid(string, required): Project GIDopt_fields(string, optional): Comma-separated fields to include
Example:
project = await get_project(project_gid="9876543210")
# With all fields
project = await get_project(
project_gid="9876543210",
opt_fields="name,notes,due_date,start_date,color,owner,team,members,archived,public,created_at,modified_at"
)
# Returns:
# {
# "data": {
# "gid": "9876543210",
# "name": "Website Redesign",
# "notes": "Complete redesign of company website",
# "due_date": "2025-12-31",
# "start_date": "2025-10-01",
# "color": "light-blue",
# "owner": {
# "gid": "1111111111",
# "name": "John Doe"
# },
# "team": {
# "gid": "2222222222",
# "name": "Marketing"
# },
# "archived": false,
# "public": true,
# "created_at": "2025-10-01T00:00:00.000Z",
# "modified_at": "2025-10-08T15:00:00.000Z"
# }
# }create_project
Create a new project.
Parameters:
workspace(string, required): Workspace GIDname(string, required): Project namenotes(string, optional): Project descriptioncolor(string, optional): Project color (see color list below)due_date(string, optional): Due date (YYYY-MM-DD)start_date(string, optional): Start date (YYYY-MM-DD)public(bool, optional): Public to organization (default: true)
Project Colors:
Light: light-pink, light-green, light-orange, light-yellow, light-teal, light-blue, light-purple, light-warm-gray
Dark: dark-pink, dark-green, dark-orange, dark-yellow, dark-teal, dark-blue, dark-purple, dark-warm-gray
Example:
# Simple project
project = await create_project(
workspace="1234567890",
name="Q4 Marketing Campaign"
)
# Full project
project = await create_project(
workspace="1234567890",
name="Product Launch",
notes="Launch new product line in Q1 2026",
color="light-blue",
due_date="2026-03-31",
start_date="2025-11-01",
public=True
)
# Returns:
# {
# "data": {
# "gid": "9876543211",
# "name": "Product Launch",
# "notes": "Launch new product line in Q1 2026",
# "color": "light-blue",
# "due_date": "2026-03-31",
# "start_date": "2025-11-01",
# "public": true
# }
# }Task Management
list_tasks
List tasks with filters.
Parameters:
project(string, optional): Filter by project GIDsection(string, optional): Filter by section GIDassignee(string, optional): Filter by assignee GID (or "me")workspace(string, optional): Workspace GID (required if not using project/section)completed_since(string, optional): Tasks completed after this time (ISO 8601)modified_since(string, optional): Tasks modified after this time (ISO 8601)limit(int, optional): Results per page (default: 20, max: 100)opt_fields(string, optional): Comma-separated fields to include
Example:
# All tasks in project
tasks = await list_tasks(project="9876543210")
# My tasks
tasks = await list_tasks(
workspace="1234567890",
assignee="me"
)
# Tasks in section
tasks = await list_tasks(section="5555555555")
# Recently completed
tasks = await list_tasks(
project="9876543210",
completed_since="2025-10-01T00:00:00Z"
)
# With specific fields
tasks = await list_tasks(
project="9876543210",
opt_fields="name,completed,due_on,assignee,tags"
)
# Returns:
# {
# "data": [
# {
# "gid": "1111111111",
# "name": "Design homepage mockup",
# "resource_type": "task"
# }
# ]
# }get_task
Get detailed information about a task.
Parameters:
task_gid(string, required): Task GIDopt_fields(string, optional): Comma-separated fields to include
Example:
task = await get_task(task_gid="1111111111")
# With all fields
task = await get_task(
task_gid="1111111111",
opt_fields="name,notes,completed,assignee,due_on,start_on,tags,projects,memberships,num_subtasks,parent,followers,created_at,modified_at"
)
# Returns:
# {
# "data": {
# "gid": "1111111111",
# "name": "Design homepage mockup",
# "notes": "Create high-fidelity mockup for new homepage design",
# "completed": false,
# "assignee": {
# "gid": "2222222222",
# "name": "Jane Smith"
# },
# "due_on": "2025-10-15",
# "start_on": "2025-10-08",
# "tags": [
# {"gid": "3333333333", "name": "design"}
# ],
# "projects": [
# {"gid": "9876543210", "name": "Website Redesign"}
# ],
# "num_subtasks": 3,
# "parent": null,
# "created_at": "2025-10-01T10:00:00.000Z",
# "modified_at": "2025-10-08T14:30:00.000Z"
# }
# }create_task
Create a new task.
Parameters:
workspace(string, optional): Workspace GID (required if projects not provided)projects(list of strings, optional): Project GIDs to add task toname(string, optional): Task name (default: empty)notes(string, optional): Task descriptionassignee(string, optional): Assignee GID (or "me")due_on(string, optional): Due date (YYYY-MM-DD)start_on(string, optional): Start date (YYYY-MM-DD)tags(list of strings, optional): Tag GIDs
Example:
# Simple task
task = await create_task(
workspace="1234567890",
name="Review quarterly reports"
)
# Task in project
task = await create_task(
projects=["9876543210"],
name="Design homepage mockup"
)
# Full task
task = await create_task(
projects=["9876543210"],
name="Implement user authentication",
notes="Add OAuth2 support for Google and GitHub",
assignee="me",
due_on="2025-10-31",
start_on="2025-10-15",
tags=["3333333333", "4444444444"]
)
# Returns:
# {
# "data": {
# "gid": "1111111112",
# "name": "Implement user authentication",
# "notes": "Add OAuth2 support for Google and GitHub",
# "assignee": {"gid": "2222222222", "name": "John Doe"},
# "due_on": "2025-10-31",
# "start_on": "2025-10-15"
# }
# }update_task
Update task details.
Parameters:
task_gid(string, required): Task GIDname(string, optional): Updated namenotes(string, optional): Updated descriptionassignee(string, optional): Updated assignee GID (or "me", or null to unassign)due_on(string, optional): Updated due date (YYYY-MM-DD, or null to clear)start_on(string, optional): Updated start date (YYYY-MM-DD, or null to clear)completed(bool, optional): Completion status
Example:
# Update name
task = await update_task(
task_gid="1111111111",
name="Updated task name"
)
# Assign task
task = await update_task(
task_gid="1111111111",
assignee="2222222222"
)
# Set due date
task = await update_task(
task_gid="1111111111",
due_on="2025-10-20"
)
# Multiple updates
task = await update_task(
task_gid="1111111111",
name="Design homepage mockup (final)",
notes="Final version incorporating feedback",
due_on="2025-10-18",
completed=False
)
# Unassign task
task = await update_task(
task_gid="1111111111",
assignee=None
)
# Returns:
# {
# "data": {
# "gid": "1111111111",
# "name": "Design homepage mockup (final)",
# ...
# }
# }complete_task
Mark task as complete.
Parameters:
task_gid(string, required): Task GID
Example:
task = await complete_task(task_gid="1111111111")
# Returns:
# {
# "data": {
# "gid": "1111111111",
# "completed": true,
# "completed_at": "2025-10-08T16:00:00.000Z"
# }
# }delete_task
Delete a task permanently.
Parameters:
task_gid(string, required): Task GID
Example:
result = await delete_task(task_gid="1111111111")
# Returns:
# {
# "data": {}
# }add_task_comment
Add a comment (story) to a task.
Parameters:
task_gid(string, required): Task GIDtext(string, required): Comment text
Example:
comment = await add_task_comment(
task_gid="1111111111",
text="Updated the mockup with client feedback"
)
# Multi-line comment
comment = await add_task_comment(
task_gid="1111111111",
text="Status update:\n\n- Completed initial design\n- Sent to client for review\n- Awaiting feedback"
)
# Returns:
# {
# "data": {
# "gid": "5555555556",
# "text": "Updated the mockup with client feedback",
# "created_at": "2025-10-08T16:15:00.000Z",
# "created_by": {
# "gid": "2222222222",
# "name": "John Doe"
# }
# }
# }Section Management
list_sections
List sections in a project.
Parameters:
project_gid(string, required): Project GIDlimit(int, optional): Results per page (default: 20, max: 100)opt_fields(string, optional): Comma-separated fields to include
Example:
sections = await list_sections(project_gid="9876543210")
# With specific fields
sections = await list_sections(
project_gid="9876543210",
opt_fields="name,created_at"
)
# Returns:
# {
# "data": [
# {
# "gid": "5555555555",
# "name": "To Do",
# "resource_type": "section"
# },
# {
# "gid": "5555555556",
# "name": "In Progress",
# "resource_type": "section"
# },
# {
# "gid": "5555555557",
# "name": "Done",
# "resource_type": "section"
# }
# ]
# }create_section
Create a section in a project.
Parameters:
project_gid(string, required): Project GIDname(string, required): Section name
Example:
section = await create_section(
project_gid="9876543210",
name="Ready for Review"
)
# Returns:
# {
# "data": {
# "gid": "5555555558",
# "name": "Ready for Review",
# "project": {
# "gid": "9876543210",
# "name": "Website Redesign"
# }
# }
# }Tag Management
list_tags
List tags in a workspace.
Parameters:
workspace(string, required): Workspace GIDlimit(int, optional): Results per page (default: 20, max: 100)opt_fields(string, optional): Comma-separated fields to include
Example:
tags = await list_tags(workspace="1234567890")
# With specific fields
tags = await list_tags(
workspace="1234567890",
opt_fields="name,color,created_at"
)
# Returns:
# {
# "data": [
# {
# "gid": "3333333333",
# "name": "design",
# "resource_type": "tag"
# },
# {
# "gid": "3333333334",
# "name": "urgent",
# "resource_type": "tag"
# }
# ]
# }create_tag
Create a new tag.
Parameters:
workspace(string, required): Workspace GIDname(string, required): Tag namecolor(string, optional): Tag color (see color list below)
Tag Colors:
Dark: dark-pink, dark-green, dark-blue, dark-red, dark-teal, dark-brown, dark-orange, dark-purple, dark-warm-gray
Light: light-pink, light-green, light-blue, light-red, light-teal, light-brown, light-orange, light-purple, light-warm-gray
None: none (no color)
Example:
# Simple tag
tag = await create_tag(
workspace="1234567890",
name="frontend"
)
# Tag with color
tag = await create_tag(
workspace="1234567890",
name="critical",
color="dark-red"
)
# Returns:
# {
# "data": {
# "gid": "3333333335",
# "name": "critical",
# "color": "dark-red"
# }
# }Search
search_workspace
Search for tasks, projects, users, portfolios, or tags.
Parameters:
workspace(string, required): Workspace GIDresource_type(string, required): Type to search (task, project, user, portfolio, tag)query(string, required): Search querylimit(int, optional): Results per page (default: 20, max: 100)opt_fields(string, optional): Comma-separated fields to include
Example:
# Search tasks
tasks = await search_workspace(
workspace="1234567890",
resource_type="task",
query="design"
)
# Search projects
projects = await search_workspace(
workspace="1234567890",
resource_type="project",
query="website"
)
# Search users
users = await search_workspace(
workspace="1234567890",
resource_type="user",
query="john"
)
# Returns:
# {
# "data": [
# {
# "gid": "1111111111",
# "name": "Design homepage mockup",
# "resource_type": "task"
# }
# ]
# }Portfolio Management
list_portfolios
List portfolios in a workspace.
Parameters:
workspace(string, required): Workspace GIDowner(string, optional): Filter by owner GID (or "me")limit(int, optional): Results per page (default: 20, max: 100)opt_fields(string, optional): Comma-separated fields to include
Example:
# All portfolios
portfolios = await list_portfolios(workspace="1234567890")
# My portfolios
portfolios = await list_portfolios(
workspace="1234567890",
owner="me"
)
# With specific fields
portfolios = await list_portfolios(
workspace="1234567890",
opt_fields="name,color,created_at,owner"
)
# Returns:
# {
# "data": [
# {
# "gid": "7777777777",
# "name": "Product Development",
# "resource_type": "portfolio"
# }
# ]
# }User Management
get_user
Get user details.
Parameters:
user_gid(string, required): User GID (or "me" for current user)opt_fields(string, optional): Comma-separated fields to include
Example:
# Current user
user = await get_user(user_gid="me")
# Specific user
user = await get_user(user_gid="2222222222")
# With all fields
user = await get_user(
user_gid="me",
opt_fields="name,email,photo,workspaces"
)
# Returns:
# {
# "data": {
# "gid": "2222222222",
# "name": "John Doe",
# "email": "john@example.com",
# "photo": {
# "image_128x128": "https://...",
# "image_60x60": "https://..."
# },
# "workspaces": [
# {
# "gid": "1234567890",
# "name": "My Company"
# }
# ]
# }
# }Common Workflows
Daily Task Management
# Get my tasks
my_tasks = await list_tasks(
workspace="1234567890",
assignee="me",
opt_fields="name,due_on,completed"
)
# Complete a task
await complete_task(task_gid="1111111111")
# Add progress update
await add_task_comment(
task_gid="1111111111",
text="Completed the first draft"
)Project Setup
# Create project
project = await create_project(
workspace="1234567890",
name="Website Redesign",
due_date="2025-12-31",
color="light-blue"
)
# Create sections
await create_section(
project_gid=project["data"]["gid"],
name="To Do"
)
await create_section(
project_gid=project["data"]["gid"],
name="In Progress"
)
await create_section(
project_gid=project["data"]["gid"],
name="Done"
)
# Create initial tasks
await create_task(
projects=[project["data"]["gid"]],
name="Create wireframes",
assignee="me",
due_on="2025-10-20"
)Team Collaboration
# Search for team member
users = await search_workspace(
workspace="1234567890",
resource_type="user",
query="jane"
)
# Assign task to team member
await update_task(
task_gid="1111111111",
assignee=users["data"][0]["gid"]
)
# Add comment with @mention
await add_task_comment(
task_gid="1111111111",
text="@Jane Smith - Can you review this design?"
)Progress Tracking
# Get project details
project = await get_project(
project_gid="9876543210",
opt_fields="name,completed_count,num_tasks"
)
# Get tasks by section
sections = await list_sections(project_gid="9876543210")
for section in sections["data"]:
tasks = await list_tasks(
section=section["gid"],
opt_fields="name,completed"
)
# Calculate section progressTask Organization
# Create tags for categorization
design_tag = await create_tag(
workspace="1234567890",
name="design",
color="light-purple"
)
dev_tag = await create_tag(
workspace="1234567890",
name="development",
color="light-blue"
)
# Create task with tags
await create_task(
projects=["9876543210"],
name="Implement responsive layout",
tags=[design_tag["data"]["gid"], dev_tag["data"]["gid"]]
)Custom Fields
Asana supports custom fields for adding metadata to tasks:
Text: Free-form text input
Number: Numeric values
Dropdown: Select from predefined options
Date: Date picker
Checkbox: Yes/no values
People: User selection
Currency: Monetary values
Custom fields require Premium or higher plans.
Task Dependencies
Tasks can have dependencies (requires Premium or higher):
Predecessor: Task that must complete before this one
Successor: Task that depends on this one completing
Best Practices
Use workspaces wisely: Organize by company or major divisions
Structure projects: Use sections for workflow stages
Tag consistently: Create tag taxonomy for categorization
Set due dates: Track deadlines and milestones
Assign work: Clear ownership and accountability
Add context: Use task descriptions and comments
Use opt_fields: Fetch only needed data for performance
Pagination: Use limit parameter for large datasets
Search effectively: Use specific queries for better results
Cache data: Avoid repeated fetching of unchanged data
GID Format
Asana uses GIDs (Global IDs) for resources:
Format: String of digits (e.g., "1234567890")
Always use as strings, not integers
Unique across all Asana
Required for all resource-specific operations
Response Format
All Asana API responses wrap data in a data field:
{
"data": {
"gid": "1234567890",
"name": "Example",
...
}
}Or for lists:
{
"data": [
{"gid": "1234567890", "name": "Item 1"},
{"gid": "1234567891", "name": "Item 2"}
]
}Error Handling
Common errors:
401 Unauthorized: Invalid or expired token
402 Payment Required: Premium feature on free plan
403 Forbidden: Insufficient permissions
404 Not Found: Resource doesn't exist or no access
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Server error (retry)