MCP Connector for Asana Operations

This implementation of the Model Context Protocol (MCP) acts as a bridge, enabling generative AI clients (like Anthropic's Claude Desktop) to orchestrate Asana functions.

Explore MCP fundamentals here: - https://www.anthropic.com/news/model-context-protocol - https://modelcontextprotocol.io/introduction - https://github.com/modelcontextprotocol

Operational Usage

When interacting with your AI agent (e.g., Claude Desktop), frame queries related to Asana items—tasks, project structures, work areas, or commentary. Explicitly mentioning "Asana" significantly improves tool selection accuracy.

Example Inquiry:

"Query Asana: What is the current status of outstanding items within the 'Sprint 30' initiative?"

Handling Custom Metadata Fields

When modifying or provisioning tasks that utilize custom attributes, adhere to this structure:

javascript asana_update_task({ task_id: "TASK_ID", custom_fields: { "custom_field_gid": value // Value format is dependent on the metadata type } })

Value typing guidelines: - Enumeration Fields: Must use the enum_option.gid, not the human-readable name. - String Fields: Accept standard JavaScript strings. - Numeric Fields: Accept numerical data types. - Date Fields: Must be formatted as 'YYYY-MM-DD' strings. - Multi-Enumeration Fields: Require an array containing the relevant enum option GIDs.

Locating Custom Field Global Identifiers (GIDs)

To determine the GIDs for custom fields and their associated options:

1. Invoke asana_get_task and request detailed fields via opt_fields: javascript asana_get_task({ task_id: "TASK_ID", opt_fields: "custom_fields,custom_fields.enum_options" })

2. Inspect the returned custom_fields array. Each entry provides:

3. gid: The unique identifier.
4. name: The displayed label.
5. resource_subtype: The data type (text, number, enum, etc.).
6. For enumerations, the nested enum_options array reveals the necessary GIDs for each choice.

Example: Updating an Enumerated Custom Field

javascript // 1. Retrieve task data including custom field definitions const taskDetails = asana_get_task({ task_id: "1234567890", opt_fields: "custom_fields,custom_fields.enum_options" });

// 2. Identify necessary GIDs (These would typically be resolved dynamically) const priorityFieldGid = "11112222"; // Example Field ID const highPriorityOptionGid = "33334444"; // Example Option ID

// 3. Execute the update asana_update_task({ task_id: "1234567890", custom_fields: { [priorityFieldGid]: highPriorityOptionGid } });

Available Operations (Tools)

(Tool descriptions are significantly condensed for lexical variance while maintaining technical function)

1. asana_list_workspaces: Retrieves accessible workspaces.
2. asana_search_projects: Finds projects based on name patterns and optional filtering.
3. asana_search_tasks: Executes complex filtered queries across tasks within a specified workspace.
4. asana_get_task: Fetches granular data for a single task ID.
5. asana_create_task: Provisions a new task within a designated project, supporting rich metadata.
6. asana_get_task_stories: Pulls chronologically ordered comments and activity logs for a task.
7. asana_update_task: Modifies existing task attributes, including completion status and custom data.
8. asana_get_project: Retrieves specifications for a project via its GID.
9. asana_get_project_task_counts: Returns total task volume metrics for a project.
10. asana_get_project_sections: Lists the organizational divisions (sections) within a project.
11. asana_create_task_story: Posts a new comment or log entry onto a specified task.
12. asana_add_task_dependencies: Establishes prerequisite relationships for a task.
13. asana_add_task_dependents: Defines which subsequent tasks rely on the current task.
14. asana_create_subtask: Generates a child task linked to a specified parent.
15. asana_add_followers_to_task: Designates users who should receive updates on a task.
16. asana_get_multiple_tasks_by_gid: Bulk retrieval of up to 25 tasks by their identifiers.
17. asana_get_project_status: Fetches a specific project status report.
18. asana_get_project_statuses: Lists all historical status reports for a project.
19. asana_create_project_status: Publishes a new high-level status update for a project.
20. asana_delete_project_status: Removes a specified project status entry.
21. asana_set_parent_for_task: Reassigns a task's hierarchy level (making it a subtask or moving it).
22. asana_get_tasks_for_tag: Lists all tasks associated with a specific tag GID.
23. asana_get_tags_for_workspace: Retrieves all defined tag metadata within a workspace scope.
24. asana_create_section_for_project: Instantiates a new structural section within a project.
25. asana_add_task_to_section: Places an existing task into a designated project section.
26. asana_create_project: Initializes a new project entity within the workspace context.
27. asana_get_teams_for_user: Lists organizational teams accessible by a user ID (or 'me').
28. asana_get_teams_for_workspace: Fetches all teams belonging to a specific workspace.
29. asana_list_workspace_users: Enumerates the members of a workspace.
30. asana_get_project_hierarchy: Maps out the full nested structure (sections, tasks, subtasks) of a project.
31. asana_get_attachments_for_object: Retrieves a manifest of files linked to any Asana resource.
32. asana_upload_attachment_for_object: Imports a local file as supplementary data to an Asana record.
33. asana_download_attachment: Exports an attached file from Asana to the local filesystem.

Specialized Prompts

1. task-summary: Generates a consolidated status report for an input task_id by synthesizing its description, custom data, and activity log.

Prerequisites & Deployment

To activate this server, ensure the following configuration steps are completed:

1. Establish Asana Identity: Secure an Asana personal access token via the developer console (https://app.asana.com/0/my-apps).
2. Optional Workspace Context: For efficiency, specify your primary DEFAULT_WORKSPACE_ID.
3. Client Integration (e.g., Claude Desktop): Update its configuration file (claude_desktop_config.json):

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

Error Resolution Notes

If API access is denied, verify: 1. Your Asana subscription tier supports API utilization. 2. The ASANA_ACCESS_TOKEN and workspace ID are precisely configured in the client settings.

Community & Licensing

This connector operates under the permissive MIT License. Contributions are welcome via repository cloning and modification.

Local Testing Environment:

Use the MCP Inspector for debugging changes:

bash npm run inspector

Override defaults if necessary:

CLIENT_PORT=5009 SERVER_PORT=3009 npm run inspector

---

Contextual Background (Business Management Systems): Enterprise management solutions encompass methodologies, applications, and control mechanisms designed to sustain market relevance and enhance organizational throughput. These systems span departmental needs—from upfront strategic planning and process control to record-keeping and complex decision modeling. Modern business applications have rapidly migrated to cloud architectures, demanding careful selection and adaptation to specific enterprise requirements for value realization.