MCP Server for Asana

1# MCP Server for Asana
2 
3[![npm version](https://badge.fury.io/js/%40roychri%2Fmcp-server-asana.svg)](https://www.npmjs.com/package/@roychri/mcp-server-asana)
4 
5This Model Context Protocol server implementation of Asana allows you
6to talk to Asana API from MCP Client such as Anthropic's Claude
7Desktop Application, and many more.
8 
9More details on MCP here:
10 - https://www.anthropic.com/news/model-context-protocol
11 - https://modelcontextprotocol.io/introduction
12 - https://github.com/modelcontextprotocol
13 
14<a href="https://glama.ai/mcp/servers/ln1qzdhwmc"><img width="380" height="200" src="https://glama.ai/mcp/servers/ln1qzdhwmc/badge" alt="mcp-server-asana MCP server" /></a>
15 
16## Environment Variables
17 
18- `ASANA_ACCESS_TOKEN`: (Required) Your Asana access token
19- `READ_ONLY_MODE`: (Optional) Set to 'true' to disable all write operations. In this mode:
20  - Tools that modify Asana data (create, update, delete) will be disabled
21  - The `create-task` prompt will be disabled
22  - Only read operations will be available
23  This is useful for testing or when you want to ensure no changes can be made to your Asana workspace.
24 
25## Usage
26 
27In the AI tool of your choice (ex: Claude Desktop) ask something about asana tasks, projects, workspaces, and/or comments. Mentioning the word "asana" will increase the chance of having the LLM pick the right tool.
28 
29Example:
30 
31> How many unfinished asana tasks do we have in our Sprint 30 project?
32 
33Another example:
34 
35![Claude Desktop Example](https://raw.githubusercontent.com/roychri/mcp-server-asana/main/mcp-server-asana-claude-example.png)
36 
37## Tools
38 
391. `asana_list_workspaces`
40    * List all available workspaces in Asana
41    * Optional input:
42        * opt_fields (string): Comma-separated list of optional fields to include
43    * Returns: List of workspaces
442. `asana_search_projects`
45    * Search for projects in Asana using name pattern matching
46    * Required input:
47        * workspace (string): The workspace to search in
48        * name_pattern (string): Regular expression pattern to match project names
49    * Optional input:
50        * archived (boolean): Only return archived projects (default: false)
51        * opt_fields (string): Comma-separated list of optional fields to include
52    * Returns: List of matching projects
533. `asana_search_tasks`
54    * Search tasks in a workspace with advanced filtering options
55    * Required input:
56        * workspace (string): The workspace to search in
57    * Optional input:
58        * text (string): Text to search for in task names and descriptions
59        * resource_subtype (string): Filter by task subtype (e.g. milestone)
60        * completed (boolean): Filter for completed tasks
61        * is_subtask (boolean): Filter for subtasks
62        * has_attachment (boolean): Filter for tasks with attachments
63        * is_blocked (boolean): Filter for tasks with incomplete dependencies
64        * is_blocking (boolean): Filter for incomplete tasks with dependents
65        * assignee, projects, sections, tags, teams, and many other advanced filters
66        * sort_by (string): Sort by due_date, created_at, completed_at, likes, modified_at (default: modified_at)
67        * sort_ascending (boolean): Sort in ascending order (default: false)
68        * opt_fields (string): Comma-separated list of optional fields to include
69        * custom_fields (object): Object containing custom field filters
70    * Returns: List of matching tasks
714. `asana_get_task`
72    * Get detailed information about a specific task
73    * Required input:
74        * task_id (string): The task ID to retrieve
75    * Optional input:
76        * opt_fields (string): Comma-separated list of optional fields to include
77    * Returns: Detailed task information
785. `asana_create_task`
79    * Create a new task in a project
80    * Required input:
81        * project_id (string): The project to create the task in
82        * name (string): Name of the task
83    * Optional input:
84        * notes (string): Description of the task
85        * html_notes (string): HTML-like formatted description of the task
86        * due_on (string): Due date in YYYY-MM-DD format
87        * assignee (string): Assignee (can be 'me' or a user ID)
88        * followers (array of strings): Array of user IDs to add as followers
89        * parent (string): The parent task ID to set this task under
90        * projects (array of strings): Array of project IDs to add this task to
91        * resource_subtype (string): The type of the task (default_task or milestone)
92        * custom_fields (object): Object mapping custom field GID strings to their values
93    * Returns: Created task information
946. `asana_get_task_stories`
95    * Get comments and stories for a specific task
96    * Required input:
97        * task_id (string): The task ID to get stories for
98    * Optional input:
99        * opt_fields (string): Comma-separated list of optional fields to include
100    * Returns: List of task stories/comments
1017. `asana_update_task`
102    * Update an existing task's details
103    * Required input:
104        * task_id (string): The task ID to update
105    * Optional input:
106        * name (string): New name for the task
107        * notes (string): New description for the task
108        * html_notes (string): HTML-like formatted description of the task (subset of HTML tags supported)
109        * due_on (string): New due date in YYYY-MM-DD format
110        * assignee (string): New assignee (can be 'me' or a user ID)
111        * followers (array): Array of user IDs to add as followers
112        * parent (string): The parent task ID to move this task under
113        * completed (boolean): Mark task as completed or not
114        * resource_subtype (string): The type of the task (default_task or milestone)
115        * custom_fields (object): Object mapping custom field GID strings to their values
116    * Returns: Updated task information
1178. `asana_get_project`
118    * Get detailed information about a specific project
119    * Required input:
120        * project_id (string): The project ID to retrieve
121    * Optional input:
122        * opt_fields (string): Comma-separated list of optional fields to include
123    * Returns: Detailed project information
1249. `asana_get_project_task_counts`
125    * Get the number of tasks in a project
126    * Required input:
127        * project_id (string): The project ID to get task counts for
128    * Optional input:
129        * opt_fields (string): Comma-separated list of optional fields to include
130    * Returns: Task count information
13110. `asana_get_project_sections`
132    * Get sections in a project
133    * Required input:
134        * project_id (string): The project ID to get sections for
135    * Optional input:
136        * opt_fields (string): Comma-separated list of optional fields to include
137    * Returns: List of project sections
13811. `asana_create_task_story`
139    * Create a comment or story on a task
140    * Required input:
141        * task_id (string): The task ID to add the story to
142        * text (string): The text content of the story/comment
143    * Optional input:
144        * opt_fields (string): Comma-separated list of optional fields to include
145    * Returns: Created story information
14612. `asana_add_task_dependencies`
147    * Set dependencies for a task
148    * Required input:
149        * task_id (string): The task ID to add dependencies to
150        * dependencies (array of strings): Array of task IDs that this task depends on
151    * Returns: Updated task dependencies
15213. `asana_add_task_dependents`
153    * Set dependents for a task (tasks that depend on this task)
154    * Required input:
155        * task_id (string): The task ID to add dependents to
156        * dependents (array of strings): Array of task IDs that depend on this task
157    * Returns: Updated task dependents
15814. `asana_create_subtask`
159    * Create a new subtask for an existing task
160    * Required input:
161        * parent_task_id (string): The parent task ID to create the subtask under
162        * name (string): Name of the subtask
163    * Optional input:
164        * notes (string): Description of the subtask
165        * due_on (string): Due date in YYYY-MM-DD format
166        * assignee (string): Assignee (can be 'me' or a user ID)
167        * opt_fields (string): Comma-separated list of optional fields to include
168    * Returns: Created subtask information
16915. `asana_get_multiple_tasks_by_gid`
170    * Get detailed information about multiple tasks by their GIDs (maximum 25 tasks)
171    * Required input:
172        * task_ids (array of strings or comma-separated string): Task GIDs to retrieve (max 25)
173    * Optional input:
174        * opt_fields (string): Comma-separated list of optional fields to include
175    * Returns: List of detailed task information
17616. `asana_get_project_status`
177    * Get a project status update
178    * Required input:
179        * project_status_gid (string): The project status GID to retrieve
180    * Optional input:
181        * opt_fields (string): Comma-separated list of optional fields to include
182    * Returns: Project status information
18317. `asana_get_project_statuses`
184    * Get all status updates for a project
185    * Required input:
186        * project_gid (string): The project GID to get statuses for
187    * Optional input:
188        * limit (number): Results per page (1-100)
189        * offset (string): Pagination offset token
190        * opt_fields (string): Comma-separated list of optional fields to include
191    * Returns: List of project status updates
19218. `asana_create_project_status`
193    * Create a new status update for a project
194    * Required input:
195        * project_gid (string): The project GID to create the status for
196        * text (string): The text content of the status update
197    * Optional input:
198        * color (string): The color of the status (green, yellow, red)
199        * title (string): The title of the status update
200        * html_text (string): HTML formatted text for the status update
201        * opt_fields (string): Comma-separated list of optional fields to include
202    * Returns: Created project status information
20319. `asana_delete_project_status`
204    * Delete a project status update
205    * Required input:
206        * project_status_gid (string): The project status GID to delete
207    * Returns: Deletion confirmation
20820. `asana_set_parent_for_task`
209    * Set the parent of a task and position the subtask within the other subtasks of that parent
210    * Required input:
211        * task_id (string): The task ID to operate on
212        * data (object):
213            * parent (string): The new parent of the task, or null for no parent
214    * Optional input:
215        * insert_after (string): A subtask of the parent to insert the task after, or null to insert at the beginning of the list
216        * insert_before (string): A subtask of the parent to insert the task before, or null to insert at the end of the list
217        * opt_fields (string): Comma-separated list of optional fields to include
218    * Returns: Updated task information
21921. `asana_get_tag`
220    * Get detailed information about a specific tag
221    * Required input:
222        * tag_gid (string): Globally unique identifier for the tag
223    * Optional input:
224        * opt_fields (string): Comma-separated list of optional fields to include
225    * Returns: Detailed tag information
22622. `asana_get_tags_for_task`
227    * Get a task's tags
228    * Required input:
229        * task_gid (string): The task to operate on
230    * Optional input:
231        * limit (number): Results per page. The number of objects to return per page. The value must be between 1 and 100.
232        * offset (string): Offset token. An offset to the next page returned by the API.
233        * opt_fields (string): Comma-separated list of optional fields to include
234    * Returns: List of tags associated with the task
23523. `asana_get_tasks_for_tag`
236    * Get tasks for a specific tag
237    * Required input:
238        * tag_gid (string): The tag GID to retrieve tasks for
239    * Optional input:
240        * opt_fields (string): Comma-separated list of optional fields to include
241        * opt_pretty (boolean): Provides the response in a 'pretty' format
242        * limit (integer): The number of objects to return per page. The value must be between 1 and 100.
243        * offset (string): An offset to the next page returned by the API.
244    * Returns: List of tasks for the specified tag
24524. `asana_get_tags_for_workspace`
246    * Get tags in a workspace
247    * Required input:
248        * workspace_gid (string): Globally unique identifier for the workspace or organization
249    * Optional input:
250        * limit (integer): Results per page. The number of objects to return per page. The value must be between 1 and 100.
251        * offset (string): Offset token. An offset to the next page returned by the API.
252        * opt_fields (string): Comma-separated list of optional fields to include
253    * Returns: List of tags in the workspace
25425. `asana_update_tag`
255    * Update an existing tag
256    * Required input:
257        * tag_gid (string): Globally unique identifier for the tag
258    * Optional input:
259        * name (string): Name of the tag
260        * color (string): Color of the tag. Can be one of: dark-pink, dark-green, dark-blue, dark-red, dark-teal, dark-brown, dark-orange, dark-purple, dark-warm-gray, light-pink, light-green, light-blue, light-red, light-teal, light-brown, light-orange, light-purple, light-warm-gray
261        * notes (string): Notes about the tag
262        * opt_fields (string): Comma-separated list of optional fields to include
263    * Returns: Updated tag information
26426. `asana_delete_tag`
265    * Delete a tag
266    * Required input:
267        * tag_gid (string): Globally unique identifier for the tag
268    * Returns: Deletion confirmation
26927. `asana_create_tag_for_workspace`
270    * Create a new tag in a workspace
271    * Required input:
272        * workspace_gid (string): Globally unique identifier for the workspace or organization
273        * name (string): Name of the tag
274    * Optional input:
275        * color (string): Color of the tag. Can be one of: dark-pink, dark-green, dark-blue, dark-red, dark-teal, dark-brown, dark-orange, dark-purple, dark-warm-gray, light-pink, light-green, light-blue, light-red, light-teal, light-brown, light-orange, light-purple, light-warm-gray
276        * notes (string): Notes about the tag
277        * opt_fields (string): Comma-separated list of optional fields to include
278    * Returns: Created tag information
27928. `asana_add_tag_to_task`
280    * Add a tag to a task
281    * Required input:
282        * task_gid (string): The task GID to add the tag to
283        * tag_gid (string): The tag GID to add to the task
284    * Returns: Success response
28529. `asana_remove_tag_from_task`
286    * Remove a tag from a task
287    * Required input:
288        * task_gid (string): The task GID to remove the tag from
289        * tag_gid (string): The tag GID to remove from the task
290    * Returns: Success response
29130. `asana_add_project_to_task`
292    * Add an existing task to a project
293    * Required input:
294        * task_id (string): The task ID to add to the project
295        * project_id (string): The project ID to add the task to
296    * Optional input:
297        * section (string): The section ID to add the task to within the project
298        * insert_after (string): A task ID to insert this task after. At most one of insert_before, insert_after, or section should be specified.
299        * insert_before (string): A task ID to insert this task before. At most one of insert_before, insert_after, or section should be specified.
300    * Returns: Success message confirming the task was added to the project
301    * Notes: If no positioning arguments are given, the task will be added to the end of the project
30231. `asana_remove_project_from_task`
303    * Remove a task from a project
304    * Required input:
305        * task_id (string): The task ID to remove from the project
306        * project_id (string): The project ID to remove the task from
307    * Returns: Success message confirming the task was removed from the project
308    * Notes: The task will still exist in the system, but it will not be in the project anymore
30932. `asana_delete_task`
310    * Delete a task permanently
311    * Required input:
312        * task_id (string): The task ID to delete
313    * Returns: Success message confirming the task was deleted
314    * Notes: This action cannot be undone. The task will be permanently removed.
31533. `asana_create_project`
316    * Create a new project in a workspace or team
317    * Required input:
318        * workspace (string): The workspace GID to create the project in
319        * name (string): Name of the project
320    * Optional input:
321        * team (string): The team GID (required for organization workspaces)
322        * notes (string): Description or notes for the project
323        * color (string): Color of the project (e.g., dark-pink, dark-green, light-blue)
324        * privacy_setting (string): Privacy setting (public_to_workspace, private_to_team, private)
325        * default_view (string): Default view (list, board, calendar, timeline)
326        * opt_fields (string): Comma-separated list of optional fields to include
327    * Returns: The created project object
328 
329## Prompts
330 
3311. `task-summary`
332    * Get a summary and status update for a task based on its notes, custom fields and comments
333    * Required input:
334        * task_id (string): The task ID to get summary for
335    * Returns: A detailed prompt with instructions for generating a task summary
336 
3372. `task-completeness`
338    * Analyze if a task description contains all necessary details for completion
339    * Required input:
340        * task_id (string): The task ID or URL to analyze
341    * Returns: A detailed prompt with instructions for analyzing task completeness
342 
3433. `create-task`
344    * Create a new task with specified details
345    * Required input:
346        * project_name (string): The name of the Asana project where the task should be created
347        * title (string): The title of the task
348    * Optional input:
349        * notes (string): Notes or description for the task
350        * due_date (string): Due date for the task (YYYY-MM-DD format)
351    * Returns: A detailed prompt with instructions for creating a comprehensive task
352 
353## Resources
354 
3551. Workspaces - `asana://workspace/{workspace_gid}`
356   * Representation of Asana workspaces as resources
357   * Each workspace is exposed as a separate resource
358   * URI Format: `asana://workspace/{workspace_gid}`
359   * Returns: JSON object with workspace details including:
360     * `name`: Workspace name (string)
361     * `id`: Workspace global ID (string)
362     * `type`: Resource type (string)
363     * `is_organization`: Whether the workspace is an organization (boolean)
364     * `email_domains`: List of email domains associated with the workspace (string[])
365   * Mime Type: `application/json`
366 
3672. Projects - `asana://project/{project_gid}`
368   * Template resource for retrieving project details by GID
369   * URI Format: `asana://project/{project_gid}`
370   * Returns: JSON object with project details including:
371     * `name`: Project name (string)
372     * `id`: Project global ID (string)
373     * `type`: Resource type (string)
374     * `archived`: Whether the project is archived (boolean)
375     * `public`: Whether the project is public (boolean)
376     * `notes`: Project description/notes (string)
377     * `color`: Project color (string)
378     * `default_view`: Default view type (string)
379     * `due_date`, `due_on`, `start_on`: Project date information (string)
380     * `workspace`: Object containing workspace information
381     * `team`: Object containing team information
382     * `sections`: Array of section objects in the project
383     * `custom_fields`: Array of custom field definitions for the project
384   * Mime Type: `application/json`
385 
386## Setup
387 
388 
3891. **Create an Asana account**:
390 
391   - Visit the [Asana](https://www.asana.com).
392   - Click "Sign up".
393 
3942. **Retrieve the Asana Access Token**:
395 
396   - You can generate a personal access token from the Asana developer console.
397     - https://app.asana.com/0/my-apps
398   - More details here: https://developers.asana.com/docs/personal-access-token
399 
4003. **Installation Options**:
401 
402   ### For Claude Desktop:
403   Add the following to your `claude_desktop_config.json`:
404 
405   ```json
406   {
407     "mcpServers": {
408       "asana": {
409         "command": "npx",
410         "args": ["-y", "@roychri/mcp-server-asana"],
411         "env": {
412           "ASANA_ACCESS_TOKEN": "your-asana-access-token"
413         }
414       }
415     }
416   }
417   ```
418   
419   ### For Claude Code:
420   
421   Use the following command to install and configure the MCP server:
422   
423   ```bash
424   claude mcp add asana -e ASANA_ACCESS_TOKEN=<TOKEN> -- npx -y @roychri/mcp-server-asana
425   ```
426   
427   Replace `<TOKEN>` with your Asana access token.
428 
429If you want to install the beta version (not yet released), you can use:
430 
431* `@roychri/mcp-server-asana@beta`
432 
433You can find the current beta release, if any, with either:
434 
4351. https://www.npmjs.com/package/@roychri/mcp-server-asana?activeTab=versions
4362. `npm dist-tag ls @roychri/mcp-server-asana`
437 
438## Troubleshooting
439 
440If you encounter permission errors:
441 
4421. Ensure the asana plan you have allows API access
4432. Confirm the access token and configuration are correctly set in `claude_desktop_config.json`.
444 
445 
446## Contributing
447 
448Clone this repo and start hacking.
449 
450### Test it locally with the MCP Inspector
451 
452If you want to test your changes, you can use the MCP Inspector like this:
453 
454```bash
455npm run inspector
456```
457 
458This will expose the client to port `5173` and server to port `3000`.
459 
460If those ports are already used by something else, you can use:
461 
462```bash
463CLIENT_PORT=5009 SERVER_PORT=3009 npm run inspector
464```
465 
466## License
467 
468This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
469