Asana MCP server

The MCP Server for Asana enables you to interact with the Asana API through Model Context Protocol (MCP) clients such as Claude Desktop. This integration allows you to query and manage your Asana tasks, projects, workspaces, and more directly from your AI assistant.

Installation

Prerequisites

1. Create an Asana account:

   • Visit Asana
   • Click "Sign up"

2. Retrieve your Asana Access Token:

   • Generate a personal access token from the Asana developer console
   • For more information, visit Asana's documentation on personal access tokens

3. Optional: Get your default workspace ID:

   • If you primarily work with one workspace, setting a default workspace ID simplifies API calls
   • You can find your workspace ID in the URL when viewing your workspace in Asana

Configuration for Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "asana": {
      "command": "npx",
      "args": ["-y", "@cristip73/mcp-server-asana"],
      "env": {
        "ASANA_ACCESS_TOKEN": "your-asana-access-token",
        "DEFAULT_WORKSPACE_ID": "your-default-workspace-id"
      }
    }
  }
}

Usage

Basic Usage

In your AI tool (like Claude Desktop), simply ask about Asana tasks, projects, or workspaces. Including the word "asana" in your query helps the AI select the right tool.

Example queries:

• "How many unfinished asana tasks do we have in our Sprint 30 project?"
• "Show me all high priority tasks in our Marketing project in Asana"
• "Create a new task in Asana for the Design team due next Friday"

Working with Custom Fields

When updating or creating tasks with custom fields, use the following format:

asana_update_task({
  task_id: "TASK_ID",
  custom_fields: {
    "custom_field_gid": value  // The value format depends on the field type
  }
})

The value format varies by field type:

• Enum fields: Use the enum_option.gid of the option
• Text fields: Use a string
• Number fields: Use a number
• Date fields: Use a string in YYYY-MM-DD format
• Multi-enum fields: Use an array of enum option GIDs

Finding Custom Field GIDs

To find the GIDs of custom fields and their enum options:

1. Get task details with custom fields:

   asana_get_task({
     task_id: "TASK_ID",
     opt_fields: "custom_fields,custom_fields.enum_options"
   })
   

2. In the response, examine the custom_fields array to find:

   • gid: The unique identifier for the custom field
   • name: The display name
   • resource_subtype: The field type
   • For enum fields, check the enum_options array for the GID of each option

Example: Updating an Enum Custom Field

// First, get the task with custom fields
const taskDetails = asana_get_task({
  task_id: "1234567890",
  opt_fields: "custom_fields,custom_fields.enum_options"
});

// Find the custom field GID and enum option GID
const priorityFieldGid = "11112222";  // From taskDetails.custom_fields
const highPriorityOptionGid = "33334444";  // From the enum_options of the priority field

// Update the task with the custom field
asana_update_task({
  task_id: "1234567890",
  custom_fields: {
    [priorityFieldGid]: highPriorityOptionGid
  }
});

Available Tools

Workspace Management

• asana_list_workspaces: List all available workspaces
• asana_list_workspace_users: Get users in a workspace
• asana_get_teams_for_workspace: Get teams in a workspace
• asana_get_teams_for_user: Get teams for a specific user
• asana_get_tags_for_workspace: Get tags in a workspace

Project Management

• asana_search_projects: Search for projects by name pattern
• asana_get_project: Get details about a specific project
• asana_create_project: Create a new project
• asana_get_project_sections: Get sections in a project
• asana_create_section_for_project: Create a new section in a project
• asana_get_project_task_counts: Get the number of tasks in a project
• asana_get_project_hierarchy: Get the complete hierarchical structure of a project
• asana_get_project_status: Get a specific project status update
• asana_get_project_statuses: Get all status updates for a project
• asana_create_project_status: Create a new status update for a project
• asana_delete_project_status: Delete a project status update

Task Management

• asana_search_tasks: Search tasks with advanced filtering options
• asana_get_task: Get detailed information about a task
• asana_create_task: Create a new task
• asana_update_task: Update an existing task
• asana_get_task_stories: Get comments and stories for a task
• asana_create_task_story: Create a comment on a task
• asana_create_subtask: Create a new subtask
• asana_get_multiple_tasks_by_gid: Get details about multiple tasks (up to 25)
• asana_add_task_to_section: Add a task to a specific section
• asana_add_task_dependencies: Set dependencies for a task
• asana_add_task_dependents: Set tasks that depend on a task
• asana_add_followers_to_task: Add followers to a task
• asana_set_parent_for_task: Set the parent of a task
• asana_get_tasks_for_tag: Get tasks for a specific tag

Attachments

• asana_get_attachments_for_object: List attachments for a task or project
• asana_upload_attachment_for_object: Upload a file as an attachment
• asana_download_attachment: Download an attachment to a local directory

Prompts

• task-summary: Generate a summary and status update for a task

Troubleshooting

If you encounter permission errors:

1. Ensure your Asana plan allows API access
2. Confirm your access token and configuration are correctly set in claude_desktop_config.json
3. Check that your token has the necessary permissions for the operations you're attempting

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.