Asana MCP Server

Exposes asana_create_task tool through MCP protocol that accepts JSON schema-validated parameters (name, description, assignee, due_date, projects, tags) and translates them into Asana REST API POST requests. Uses TypeScript type definitions and runtime validation to ensure only valid Asana field types are submitted, preventing malformed API calls before they reach Asana's servers.

Implements asana_search_tasks tool that queries Asana's task search endpoint with filters across workspace, project, assignee, tag, and status fields. Translates MCP parameters into Asana's query syntax (e.g., 'assignee:gid' format) and returns paginated results with task metadata (GID, name, assignee, due date, completion status). Supports both simple text search and structured field-based filtering.

Exposes asana_get_project tool that retrieves full project metadata including sections array with section GIDs and names. Sections are organizational containers within projects that group related tasks. Tool returns section structure enabling AI clients to understand project layout and determine correct section for task placement. Sections are read-only through MCP — creation/deletion not supported.

Implements asana_update_task tool that modifies specific task fields (name, description, assignee, due_date, completed status, custom fields) through Asana's PATCH endpoint. Uses selective field update pattern — only provided fields are modified, leaving others unchanged. Validates field types before submission and returns updated task metadata. Supports both simple fields (name, description) and complex fields (custom fields, assignee).

Exposes asana_get_workspaces tool that lists all workspaces accessible to the authenticated user. Returns workspace metadata (GID, name, is_organization) enabling AI clients to discover available workspaces and select correct workspace for subsequent operations. Workspace enumeration is required step before accessing projects or tasks since all Asana entities are scoped to workspaces.

Implements asana_get_task tool that retrieves complete task metadata including standard fields (name, description, assignee, due_date, completed) and custom fields with their values. Uses Asana's task detail endpoint with field expansion to include related data (assignee details, project info, custom field definitions and values). Returns comprehensive task context enabling AI clients to understand full task state.

Implements error handling layer that catches Asana API errors (4xx, 5xx responses) and validation errors (invalid parameters, missing required fields) and returns structured error responses through MCP protocol. Maps Asana API error codes to human-readable messages and includes error context (which field failed, why) enabling AI clients to understand failure reasons and retry appropriately. Validation happens before API calls to prevent wasted requests.

Exposes asana_add_task_dependency and asana_remove_task_dependency tools that manage task blocking relationships through Asana's dependency API. Translates MCP requests into Asana's dependency endpoint calls, supporting 'blocks' and 'is_blocked_by' relationship types. Validates that both task GIDs exist before attempting relationship creation, preventing orphaned dependencies.

Implements asana://project/{gid} and asana://workspace/{gid} resource URIs that expose project metadata (name, description, owner, sections, custom fields) and workspace structure through MCP's resource system. Caches project/workspace data in memory and returns structured JSON containing section lists, allowing AI clients to understand project organization without multiple API calls. Resources are read-only and populated on-demand.

Exposes asana_add_comment and asana_get_task_stories tools that manage task comments (stories) through Asana's stories API. Translates MCP requests into Asana story endpoints, supporting text comment creation and retrieval of full task activity history (comments, field changes, assignments). Returns story metadata including author, timestamp, and comment text, enabling AI clients to understand task discussion context.

Implements asana_add_tag and asana_remove_tag tools that manage task tags through Asana's tag API. Translates MCP requests into Asana tag endpoints, supporting tag addition/removal from tasks. Tags are workspace-level entities that can be used for cross-project organization. Works in conjunction with task search filtering to enable tag-based task discovery and categorization.

Provides three built-in MCP prompts (task-summary, task-completeness, create-task) that guide AI clients through structured workflows for common Asana operations. Prompts are pre-written instructions that help LLMs understand task context, validate task completeness before creation, and summarize task status. Prompts are registered in MCP server and returned via prompts/list endpoint, enabling MCP clients to surface them as suggested workflows.

Implements READ_ONLY_MODE environment variable that dynamically disables write-operation tools (create_task, update_task, add_comment, add_tag, etc.) at server initialization time. When enabled, tool registry excludes mutation tools entirely, and prompts that trigger mutations are hidden. Uses conditional tool registration pattern to enforce access control without runtime checks on every request.

Manages Asana API authentication by accepting personal access tokens or OAuth2 credentials through environment variables (ASANA_TOKEN) and wrapping all Asana API requests with Bearer token authentication. Uses TypeScript Asana SDK or direct HTTP client with Authorization headers. Validates token validity on server startup and fails fast if credentials are invalid, preventing silent authentication failures during tool execution.

Implements MCP server using stdio transport that reads JSON-RPC 2.0 requests from stdin and writes responses to stdout. Uses @modelcontextprotocol/sdk to handle protocol marshaling, request routing, and response serialization. Supports three MCP capabilities: tools (for function calling), prompts (for workflow templates), and resources (for structured data access). Transport is stateless — each request is independent with no session management.