# linear-mcp

A [Linear](https://linear.app) MCP server for Dedalus.

## Prerequisites

- Python 3.11+
- [`uv`](https://docs.astral.sh/uv/)
- A Linear workspace

## Setup

```bash
cd linear-mcp
cp .env.example .env   # then fill in your values
uv sync
```

### Environment variables

Linear uses OAuth2 for authentication. The Dedalus platform (DAuth) handles the
OAuth flow. The MCP server declares the secret name it needs (e.g. `LINEAR_ACCESS_TOKEN`).

OAuth provider configuration (consumed by the Dedalus platform):

| Variable | Description |
| --- | --- |
| `OAUTH_ENABLED` | `true` |
| `OAUTH_AUTHORIZE_URL` | `https://linear.app/oauth/authorize` |
| `OAUTH_TOKEN_URL` | `https://api.linear.app/oauth/token` |
| `OAUTH_CLIENT_ID` | Your Linear OAuth app client ID |
| `OAUTH_CLIENT_SECRET` | Your Linear OAuth app client secret |
| `OAUTH_SCOPES_AVAILABLE` | `read,write,issues:create,comments:create` |
| `OAUTH_BASE_URL` | `https://api.linear.app` |

Dedalus client configuration (for `_client.py` testing):

| Variable | Description |
| --- | --- |
| `DEDALUS_API_KEY` | Your Dedalus API key (`dsk_*`) |
| `DEDALUS_API_URL` | Defaults to `https://api.dedaluslabs.ai` |
| `DEDALUS_AS_URL` | Defaults to `https://as.dedaluslabs.ai` |

## Run the server

```bash
uv run src/main.py
```

## Test locally

```bash
uv run src/_client.py
```

This opens an interactive agent loop. On first use, DAuth will prompt you to
complete the Linear OAuth flow in your browser.

## Lint and typecheck

```bash
uv run --group lint ruff format src/
uv run --group lint ruff check src/ --fix
uv run --group lint ty check src/
```

## Available tools

| Tool                      | R/W | Description                                |
| ------------------------- | --- | ------------------------------------------ |
| `linear_get_issue`        | R   | Get issue by ID or identifier (ENG-123)    |
| `linear_list_issues`      | R   | List issues with filters                   |
| `linear_create_issue`     | W   | Create a new issue                         |
| `linear_update_issue`     | W   | Update an existing issue                   |
| `linear_list_comments`    | R   | List comments on an issue                  |
| `linear_create_comment`   | W   | Add a comment to an issue                  |
| `linear_get_project`      | R   | Get project by ID                          |
| `linear_list_projects`    | R   | List projects                              |
| `linear_create_project`   | W   | Create a new project                       |
| `linear_update_project`   | W   | Update an existing project                 |
| `linear_list_cycles`      | R   | List cycles for a team                     |
| `linear_get_cycle`        | R   | Get a cycle by ID                          |
| `linear_active_cycle`     | R   | Get the current active cycle for a team    |
| `linear_list_teams`       | R   | List all teams                             |
| `linear_get_team`         | R   | Get a team by ID                           |
| `linear_list_team_states` | R   | List workflow states (statuses) for a team |
| `linear_whoami`           | R   | Get authenticated user profile             |
| `linear_list_users`       | R   | List workspace members                     |
| `linear_list_labels`      | R   | List labels                                |
| `linear_create_label`     | W   | Create a new label                         |
| `linear_search_issues`    | R   | Full-text search across issues             |

**21 tools** (14 read, 7 write)

## Architecture

Linear uses a single GraphQL endpoint (`POST /graphql`) for all operations. The
request layer in `src/linear/request.py` dispatches queries through Dedalus's HTTP
enclave, which injects OAuth credentials transparently.

```plaintext
src/
├── linear/
│   ├── config.py      # Connection definition (OAuth)
│   ├── request.py     # GraphQL dispatch + coercion helpers
│   └── types.py       # Typed dataclass models
├── tools/
│   ├── issues.py      # Issue CRUD
│   ├── comments.py    # Comment operations
│   ├── projects.py    # Project CRUD
│   ├── cycles.py      # Cycle queries
│   ├── teams.py       # Team + workflow states
│   ├── users.py       # User queries
│   ├── labels.py      # Label operations
│   └── search.py      # Issue search
├── server.py          # MCPServer setup
├── main.py            # Entry point
└── _client.py         # Interactive agent loop (DAuth)
```

## Notes

- Linear's API is **GraphQL-only**. Every tool dispatches a GraphQL query or mutation.
- Workflow states (statuses) vary per team. Use `linear_list_team_states` to discover
  valid state IDs before creating or transitioning issues.
- Issue identifiers (e.g. `ENG-123`) can be used interchangeably with UUIDs in most tools.
- Priority values: 0 = No priority, 1 = Urgent, 2 = High, 3 = Medium, 4 = Low.
- Archived resources are hidden by default. Some tools accept `include_archived` to surface them.
- Authentication uses OAuth2 via DAuth. Personal API keys are **not** supported in this server.