# Asana Local MCP

A local, read-only [MCP](https://modelcontextprotocol.io) server for Asana.
It exposes exactly six tools that query Asana through the public REST API
with a personal access token, and it never sends a POST, PUT, PATCH, or
DELETE request. The server does not run a cloud service, does not store a
cache or index, and does not implement OAuth, webhooks, or account
registration.

**Contract at a glance**

- GET-only data plane; no mutation endpoints, no token argument in any tool
- Six tools: `list_projects`, `search_tasks`, `get_task`,
  `list_task_comments`, `search_comments`, `get_attachment`
- Token is read only from the `ASANA_ACCESS_TOKEN` environment variable
- Attachment access links stay out of task and comment output by default
- No local writes: no files, no cache, no index
- All error messages are sanitized; tokens, headers, and ephemeral URLs
  never appear in tool output or logs

## Requirements

- Python 3.11 or newer
- [uv](https://docs.astral.sh/uv/) (the lockfile is `uv.lock`)

```bash
python3 --version        # 3.11+
uv --version             # install uv first if missing
```

## Install and sync

Clone the repository and install all dependencies (including the `dev`
extras used by the test suite):

```bash
uv sync --all-extras
```

Run the full test suite:

```bash
uv run pytest -q
```

## Local run options

**Unpublished local checkout (this repository)**

Launch the server straight from the checkout. In an MCP client config, use
`uv --directory` pointed at the checkout; do not use `uvx` for an
unpublished package — `uvx asana-local-mcp` only works once the package is
published to PyPI or an index:

```bash
uv --directory /Users/coffeemug/Programming/asana-local-mcp run asana-local-mcp
```

**Editable install (development)**

```bash
uv sync --all-extras
uv run asana-local-mcp
```

**Published execution (from PyPI or an index)**

```bash
uvx asana-local-mcp
```

All entry points resolve the same console script,
`asana_local_mcp.server:main`, which serves the MCP protocol over stdio.

## Authentication

The server reads the access token exclusively from the
`ASANA_ACCESS_TOKEN` environment variable. Never pass the token as a tool
argument: no tool accepts one, and a token in any MCP client config is a
secret waiting to leak.

1. Create a personal access token in Asana (Profile > My profile settings >
   Apps > Personal access tokens). Scope it to `attachments:read` and the
   data-access scope your projects need; the attachment tools require
   `attachments:read`.
2. Add it to the **environment of your local MCP client configuration
   only**. Never paste the real value into this repository, a shell
   history, or a commit. Example `claude_desktop_config.json` (replace the
   placeholder):

```json
{
  "mcpServers": {
    "asana-local": {
      "command": "uv",
      "args": ["--directory", "/Users/coffeemug/Programming/asana-local-mcp", "run", "asana-local-mcp"],
      "env": {"ASANA_ACCESS_TOKEN": "<local-secret>"}
    }
  }
}
```

If the token is missing or blank, the server exits with code 2 and logs
exactly:

```
ASANA_ACCESS_TOKEN is missing from MCP configuration.
```

Optional: cap inline image bytes with `ASANA_INLINE_IMAGE_MAX_BYTES`
(default `2097152`, maximum `5242880`).

## Tools

All six tools are declared `read_only`. Every response is a structured
envelope:

```json
{
  "items": [],
  "returned_count": 0,
  "truncated": false,
  "next_cursor": null,
  "scope": {},
  "message": null
}
```

`returned_count` always equals `len(items)`. When `truncated` is true,
`next_cursor` or `message` explains how to continue; pass `next_cursor`
verbatim into the next call of the same tool.

### `list_projects`

Lists projects whose name contains `text`.

| Parameter | Type | Required | Default | Maximum | Description |
|-----------|------|----------|---------|---------|-------------|
| `text` | string | No | — | — | Case-insensitive name substring filter |
| `limit` | integer | No | 25 | 100 | Maximum projects to return |
| `cursor` | string | No | — | — | Continuation cursor from a prior call |

Input:

```json
{
  "text": "roadmap",
  "limit": 25,
  "cursor": null
}
```

Output items:

```json
{
  "items": [
    {"gid": "1234567890123", "name": "Roadmap 2026", "permalink_url": "https://app.asana.com/0/0/1234567890123", "archived": false}
  ],
  "returned_count": 1,
  "truncated": false,
  "next_cursor": null,
  "scope": {"searched_project_gids": []},
  "message": null
}
```

Projects are scoped to the token's accessible workspaces. `list_projects`
first enumerates workspaces visible to the token (up to 25, across at most 5
Asana API pages), then queries each workspace's project pages with an
explicit `workspace` parameter — the current Asana API can require one for
GET /projects. Project GIDs are deduplicated across workspaces. Results may
be truncated across workspace and project pages; continue with
`next_cursor` to resume.

### `search_tasks`

Searches tasks across up to 25 explicitly selected projects. This is the
only way to find tasks: discovery never leaves the selected projects.

| Parameter | Type | Required | Default | Maximum | Description |
|-----------|------|----------|---------|---------|-------------|
| `project_gids` | string array | Yes | — | 25 | Projects to scan (1–25 GIDs) |
| `text` | string | No | — | — | Case-insensitive task-name substring |
| `completed` | boolean | No | — | — | `true`/`false` to filter by completion |
| `assignee_gid` | string | No | — | — | Exact assignee GID |
| `modified_after` | string | No | — | — | ISO-8601 timestamp (e.g. `2026-08-01T00:00:00Z`) |
| `limit` | integer | No | 50 | 200 | Maximum tasks to return |

Input:

```json
{
  "project_gids": ["1234567890123"],
  "text": "launch",
  "completed": false,
  "assignee_gid": null,
  "modified_after": "2026-08-01T00:00:00Z",
  "limit": 50
}
```

Output items are deduplicated task summaries with their selected-project
memberships; a task in multiple selected projects appears once. If the
result set is truncated, retry with a narrower filter or fewer projects.

### `get_task`

Returns one task's detail fields plus normalized attachment metadata.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `task_gid` | string | Yes | Decimal Asana task GID |

Input:

```json
{
  "task_gid": "1234567890123"
}
```

Output items carry `name`, `permalink_url`, `assignee`, `due_on`,
`completed`, `modified_at`, `html_notes`, `text_notes`, `projects`,
`parent`, and `attachments` (metadata only — see the attachment policy).

### `list_task_comments`

Lists comment stories for one task, newest and oldest per Asana's story
order, under strict bounds.

| Parameter | Type | Required | Default | Maximum | Description |
|-----------|------|----------|---------|---------|-------------|
| `task_gid` | string | Yes | — | — | Decimal Asana task GID |
| `limit` | integer | No | 100 | 500 | Maximum comments to return |
| `cursor` | string | No | — | — | Continuation cursor from a prior call |

Input:

```json
{
  "task_gid": "1234567890123",
  "limit": 100,
  "cursor": null
}
```

Output items are comments with `comment_gid`, `task_gid`, `text`,
`html_text`, `created_at`, `created_by`, and `attachments` (metadata
only). Attachment metadata for comments is bounded by a shared per-call
budget of 100 fetches; when that budget runs out, the envelope message
says so. If the API repeats an offset, continuation stops and the envelope
message explains that results may be incomplete.

### `search_comments`

Searches comments across selected projects, task-first.

| Parameter | Type | Required | Default | Maximum | Description |
|-----------|------|----------|---------|---------|-------------|
| `project_gids` | string array | Yes | — | 25 | Projects to scan (1–25 GIDs) |
| `task_text` | string | No | — | — | Case-insensitive task-name filter applied before any story request |
| `comment_text` | string | No | — | — | Case-insensitive comment-text filter |
| `task_limit` | integer | No | 50 | 100 | Maximum tasks to scan |
| `comment_limit` | integer | No | 100 | 500 | Maximum comments to return |

Input:

```json
{
  "project_gids": ["1234567890123"],
  "task_text": null,
  "comment_text": "blocker",
  "task_limit": 50,
  "comment_limit": 100
}
```

The `scope` object reports `searched_project_gids`, `candidate_task_count`,
and separate `task_truncated` / `comment_truncated` flags. `task_limit` and
`comment_limit` exhaustion are reported independently in `message`.

### `get_attachment`

Returns one attachment's safe metadata, optionally with its image rendered
inline.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `attachment_gid` | string | Yes | — | Decimal Asana attachment GID |
| `include_image` | boolean | No | `false` | Render the image inline when allowed |

Input:

```json
{
  "attachment_gid": "1234567890123",
  "include_image": false
}
```

Output items carry `gid`, `name`, `resource_subtype`, `host`, `size`, and
`parent`. With `include_image: true`, a successful render adds an MCP image
content block next to the metadata envelope; any rejection is reported as
`truncated: true` with a reason in `message`. `include_image: false` never
adds an image block.

## Attachment policy

- Task and comment output carries **metadata only**. Access links
  (`download_url`, `view_url`, `permanent_url`) are omitted from task and
  comment attachments by default, so ephemeral URLs never leak into model
  context through browsing.
- `get_attachment` returns fresh, ephemeral access links only when you
  explicitly call it. Downloads may expire after a short time; re-call
  `get_attachment` for a fresh link.
- `permanent_url` is only reachable with a valid Asana session in the same
  browser, so treat it as reference metadata, not a shared link.
- `view_url` may not be present for every attachment.
- Attachment bytes are fetched without the bearer token, with an `Accept:
  image/*` header only.

## Image policy

Inline images are opt-in and strictly bounded:

- Rendering happens only when `get_attachment` is called with
  `include_image: true`.
- Only Asana-hosted attachments (`host: "asana"`) are candidates.
- Only allowlisted image MIME types render inline: `image/png`,
  `image/jpeg`, `image/gif`, `image/webp`.
- Default cap: 2 MiB (`ASANA_INLINE_IMAGE_MAX_BYTES=2097152`); hard
  ceiling: 5 MiB (`5242880`). Larger images return a `truncated: true`
  envelope with a reason message instead of bytes.
- No inline video, PDF, document, or other binary; known subtypes are
  rejected before any download.
- Nothing is ever written to disk: no local files, no cache, no index.

## Security and privacy

- **`attachments:read` is required** for the attachment tools; tokens
  without that scope get safe authentication errors.
- **GET-only data plane**: the client and the packaged entry point contain
  no POST/PUT/PATCH/DELETE path; the contract tests enforce this by
  inspecting the client source AST and by recording every request the
  transport makes.
- **No OAuth, webhooks, cache, index, or cloud deployment.** The server is
  a stdio process on your machine; it stores no state between calls beyond
  the stateless cursors you pass back.
- **No arbitrary HTML URL fetches.** Attachment discovery reads only
  `data-asana-gid` attributes from Asana HTML; URLs in HTML are never
  dereferenced.
- **No token, log, or header leakage.** Tool errors, server logs, and
  structured envelopes are sanitized: bearer tokens become `Bearer
  [REDACTED]` and URLs become `[REDACTED_URL]`. Logs record only the tool
  name and exception class.
- **`.env` is excluded from version control** (see `.gitignore`), and
  `.env.example` ships an empty token declaration with no secret.

## Error messages

Every failure is returned as an error envelope whose `message` is safe to
show. The full set:

| Condition | Message |
|-----------|---------|
| Missing/blank token | `ASANA_ACCESS_TOKEN is missing from MCP configuration.` |
| Non-decimal GID | `<field> must be a nonempty Asana GID.` |
| Limit out of range | `<field> must be between <min> and <max>.` |
| Bad timestamp | `modified_after must be an ISO-8601 timestamp.` |
| Bad continuation cursor | `cursor is invalid for this request.` |
| Authentication failure | `Asana authentication failed or access is denied.` |
| Missing resource | `Requested Asana resource is unavailable or inaccessible.` |
| Rate limit | `Asana rate limit reached. Retry after a short delay.` |
| Invalid response | `Asana returned an invalid response.` |
| Transient failure | `Asana service is temporarily unavailable. Retry shortly.` |
| Attachment bytes | `Asana attachment bytes are unavailable. Retry shortly.` |
| Pagination repeat | `Asana pagination repeated a cursor.` |
| Truncated results | Message names the bound and how to continue (for example `More matching projects may be available; continue with next_cursor.`, `Task result limit reached; narrow filters or reduce selected projects.`, `More comments may be available; continue with next_cursor.`) |
| Unexpected error | `Asana query failed unexpectedly.` |

**Narrowing or continuing truncated results**: pass the returned
`next_cursor` verbatim into the same tool with the same arguments to fetch
the next batch; or lower `limit` / add filters so the request completes
inside its bounds. Cursors are stateless and tied to the exact endpoint,
task, and filters that produced them.

## Local smoke test (manual, optional)

Never put a real credential in an automated test or a tracked file. This
smoke test uses your local client configuration only.

1. Start an MCP inspector or client pointed at the server. When run from
   this checkout, launch it with the local command, not `uvx`:
   `npx @modelcontextprotocol/inspector -- uv --directory
   /Users/coffeemug/Programming/asana-local-mcp run asana-local-mcp`, with
   the token injected through the client's `env` block as shown under
   Authentication. (`uvx asana-local-mcp` only applies to a published
   package.)
2. Call `list_projects` with `{"limit": 1}` and confirm it returns an
   accessible project from your workspace.
3. Verify shell output, server logs, and `git status` / `git grep` show no
   token, no `Authorization` header, and no attachment URL anywhere.

## Development

```bash
uv run ruff check src tests    # lint
uv run mypy src                # strict type check
uv build                       # build wheel + sdist into dist/
uv run pytest -q               # full suite (no network; mock transport only)
```

The suite includes `tests/test_read_only_contract.py`, which pins the
read-only contract: no mutation methods in the client, every recorded
request is GET, the README documents exactly the six tools the server
exposes, the tracked files carry no real secrets or signed access URLs,
error adapters strip bearer/header/URL fragments, and the whole suite
passes with `ASANA_ACCESS_TOKEN` absent. No test makes a live Asana
request.