# Linear MCP Server

MCP (Model Context Protocol) server for integrating Linear with Claude Code and other MCP clients.

## Features

- **Issue Management**: Create, update, and query Linear issues
- **Project Planning**: Create projects and break them down into milestones
- **Status Tracking**: Update issue status through workflow states
- **Progress Updates**: Add comments and progress notes to issues
- **Team Context**: Query team information and workflow states

## Installation

This project uses [uv](https://github.com/astral-sh/uv) for dependency management.

```bash
# Install dependencies
uv sync

# Or with pip
pip install -e .
```

## Configuration

1. Get your Linear API key:
   - Go to Linear Settings > Account > Security & Access
   - Create a new Personal API key
   - Choose appropriate permissions (Read, Write, Create issues, Create comments)

2. Create `.env` file:
   ```bash
   cp .env.example .env
   # Edit .env and add your LINEAR_API_KEY
   ```

## Usage with Claude Code

Add to your Claude Code configuration (`~/.claude/config.json` or project `.claude/mcp-servers.json`):

```json
{
  "mcpServers": {
    "linear": {
      "command": "uv",
      "args": ["run", "linear-mcp-server"],
      "cwd": "/Users/devonshurick/dev/personal/linear-mcp-server",
      "env": {
        "LINEAR_API_KEY": "lin_api_xxxxxxxxxxxx"
      }
    }
  }
}
```

Or use environment variables:

```json
{
  "mcpServers": {
    "linear": {
      "command": "uv",
      "args": ["run", "linear-mcp-server"],
      "cwd": "/Users/devonshurick/dev/personal/linear-mcp-server"
    }
  }
}
```

Then set `LINEAR_API_KEY` in your `.env` file.

## Available Tools

### Issue Management

- `linear_create_issue` - Create a new issue
  - Parameters: `title`, `description`, `team_id`, optional: `project_id`, `state_id`, `priority`, `assignee_id`

- `linear_update_issue` - Update an existing issue
  - Parameters: `issue_id`, optional: `state_id`, `title`, `description`, `priority`

- `linear_list_issues` - List issues for a team
  - Parameters: `team_id`, optional: `status_filter`, `assignee_id`, `limit`

- `linear_add_comment` - Add a comment to an issue
  - Parameters: `issue_id`, `body`

### Team & Workflow

- `linear_get_teams` - List available teams

- `linear_get_workflow_states` - Get workflow states for a team
  - Parameters: `team_id`

### Projects (Coming Soon)

- `linear_create_project` - Create a new project with milestones
- `linear_list_projects` - List projects

## Development

```bash
# Install with dev dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Format code
uv run black .

# Lint
uv run ruff check .
```

## Architecture

```
src/linear_mcp/
├── __init__.py
├── server.py         # MCP server implementation
├── linear_client.py  # Linear GraphQL API client
└── tools.py          # Tool definitions for MCP
```

## Use Cases

1. **Task Execution with Progress Tracking**
   - Claude receives task → Creates Linear issue → Works on task → Updates issue with progress → Marks done

2. **Project Planning**
   - User describes goal → Claude creates project → Breaks into milestones → Creates task issues → Links dependencies

3. **Dynamic Prioritization**
   - Claude reviews backlog → Analyzes priorities → Proposes changes → Updates issues after approval

## Linear API Reference

- [Linear GraphQL API](https://linear.app/developers/graphql)
- [API Schema](https://studio.apollographql.com/public/Linear-API/variant/current)
- [Rate Limits](https://linear.app/docs/api-and-webhooks): 1,500 requests/hour per API key

## License

MIT