Per-project Linear MCP setup for Claude Code (multi-workspace)

gistfile0.txt

# Per-Project Linear MCP Setup for Claude Code

Connect different Linear workspaces to different projects using the official Linear MCP server with API key auth.

## Why?

The official Linear MCP server only connects to one workspace at a time. If you have multiple Linear workspaces (e.g. Personal, Work, Client), you need per-project configuration so each project talks to the right workspace.

## Steps

### 1. Generate a Linear API key

Go to your Linear workspace settings:
```
https://linear.app/<YOUR-WORKSPACE>/settings/api
```
Create a Personal API key. Copy it.

### 2. Create `.mcp.json` in your project root

```json
{
  "mcpServers": {
    "linear-<workspace-name>": {
      "type": "http",
      "url": "https://mcp.linear.app/mcp",
      "headers": {
        "Authorization": "Bearer ${LINEAR_API_KEY}"
      }
    }
  }
}
```

Replace `<workspace-name>` with something descriptive (e.g. `linear-personal`, `linear-eventintel`).

### 3. Add the API key to `.claude/settings.local.json`

Create or edit `.claude/settings.local.json` in your project root:

```json
{
  "env": {
    "LINEAR_API_KEY": "lin_api_YOUR_KEY_HERE"
  }
}
```

### 4. Gitignore secrets

Make sure these are in your `.gitignore`:

```
.claude/settings.local.json
.env
```

`.mcp.json` is safe to commit (it only references the env var, not the actual key).

### 5. Restart Claude Code

Restart Claude Code in the project directory. The Linear MCP tools should appear automatically.

You can verify with:
```
claude mcp list
```

You should see your `linear-<workspace-name>` server with status `✓ Connected`.

## Notes

- Each project gets its own `.mcp.json` pointing to its own workspace's API key
- The env var name (`LINEAR_API_KEY`) can be anything — just make sure `.mcp.json` and `settings.local.json` match
- You can use different env var names per project if you prefer (e.g. `LINEAR_PERSONAL_API_KEY`, `LINEAR_WORK_API_KEY`)
- The `claude.ai Linear` cloud integration (if you had it connected) should be disconnected at claude.ai/settings to avoid conflicts