Content
# linear-mcp
Local MCP server for Linear workflows.
This server is designed for agents that need compact Linear tools without
loading the full Linear API surface into every context. It supports multiple API
key profiles, opt-in toolsets, read-only defaults, guarded write tools, and a
restricted GraphQL gateway for less common operations.
## Features
- Multi-profile Linear API key resolution with per-profile read-only policies.
- Small default tool surface; additional toolsets are enabled explicitly.
- Read-only GraphQL queries for exploratory or uncommon Linear reads.
- Optional write tools for issues, comments, and project updates.
- Guarded issue description edits that avoid blind full-body rewrites.
- Secret redaction and pre-push secret scanning.
## Requirements
- Node.js `22.x`
- npm
- A Linear personal API key
The project uses TypeScript ESM, `@modelcontextprotocol/sdk`, `@linear/sdk`,
`graphql`, and `zod`.
## Quick Start
```bash
npm install
cp .env.example .env
npm run build
```
Edit `.env` with at least one Linear API key:
```bash
LINEAR_API_KEY=your_linear_api_key_here
LINEAR_PROFILE=default
LINEAR_MCP_TOOLSETS=core
LINEAR_MCP_READ_ONLY=1
```
Start the stdio server:
```bash
npm start
```
For local MCP Inspector testing:
```bash
npm run inspect
```
## MCP Client Configuration
Example local MCP client entry:
```json
{
"mcpServers": {
"linear-mcp": {
"command": "node",
"args": ["/absolute/path/to/linear-mcp/dist/index.js"],
"env": {
"LINEAR_API_KEY": "your_linear_api_key_here",
"LINEAR_MCP_TOOLSETS": "core",
"LINEAR_MCP_READ_ONLY": "1"
}
}
}
}
```
Keep secrets in your client environment or local `.env`; do not commit real API
keys.
## Profiles
Use `LINEAR_API_KEY` for the default profile. Add more workspaces with
`LINEAR_<PROFILE>_API_KEY`:
```bash
LINEAR_API_KEY=your_default_linear_api_key
LINEAR_WORKSPACE_A_API_KEY=your_workspace_a_linear_api_key
LINEAR_WORKSPACE_B_API_KEY=your_workspace_b_linear_api_key
LINEAR_PROFILE=workspace-a
```
Every Linear-backed tool accepts an optional `profile` input. If omitted, the
server uses `LINEAR_PROFILE`, then falls back to `default`.
Read-only behavior is controlled globally and per profile:
```bash
LINEAR_MCP_READ_ONLY=1
LINEAR_WORKSPACE_A_MODE=readonly
LINEAR_WORKSPACE_B_MODE=readwrite
```
Global read-only mode wins. Set `LINEAR_MCP_READ_ONLY=0` before any write tool
can run.
## Toolsets
The server always registers `linear_list_profiles`. Other tools are grouped by
toolset to keep MCP context usage predictable.
Set toolsets with:
```bash
LINEAR_MCP_TOOLSETS=core,issues,catalog
```
Supported values:
- `core`
- `issues`
- `catalog`
- `planning`
- `users`
- `documents`
- `write`
- `all`
When unset, only `core` is enabled.
## Tools
Always available:
- `linear_list_profiles`
`core`:
- `linear_me`
- `linear_get_issue`
- `linear_list_issues`
- `linear_search_issues`
- `linear_get_rate_limit_status`
- `linear_graphql_query`
`issues`:
- `linear_list_my_issues`
- `linear_list_issue_comments`
- `linear_get_issue_description`
`catalog`:
- `linear_list_issue_statuses`
- `linear_get_issue_status`
- `linear_list_issue_labels`
- `linear_list_teams`
- `linear_get_team`
- `linear_list_project_labels`
`planning`:
- `linear_list_cycles`
- `linear_list_projects`
- `linear_get_project`
- `linear_list_project_milestones`
- `linear_list_project_updates`
`users`:
- `linear_get_user`
- `linear_list_users`
`documents`:
- `linear_list_documents`
- `linear_get_document`
`write`:
- `linear_create_issue`
- `linear_update_issue`
- `linear_edit_issue_description`
- `linear_create_comment`
- `linear_update_comment`
- `linear_create_project_update`
- `linear_update_project_update`
- `linear_graphql_mutation`
Write tools are registered only when `LINEAR_MCP_TOOLSETS` includes `write` and
`LINEAR_MCP_READ_ONLY=0`.
## GraphQL Gateway
`linear_graphql_query` accepts exactly one GraphQL query operation. Mutations
and subscriptions are rejected.
`linear_graphql_mutation` is disabled by default. To enable it:
```bash
LINEAR_MCP_TOOLSETS=core,write
LINEAR_MCP_READ_ONLY=0
LINEAR_MCP_MUTATION_FIELDS=issueCreate,issueUpdate,commentCreate,commentUpdate
```
Only top-level mutation fields listed in `LINEAR_MCP_MUTATION_FIELDS` are
allowed. Destructive, admin, auth, integration, webhook, import, sync, and
external-posting mutations are blocked even if allowlisted.
Prefer named write tools when they exist. Use `linear_graphql_mutation` only for
narrow operations that have been intentionally enabled.
## Safety Model
- The default mode is read-only.
- Toolsets are opt-in, so unused tools do not consume context.
- List tools return compact summaries and bounded pages.
- `linear_list_documents` returns document metadata only.
- `linear_get_document` returns bounded content plus a content hash.
- `linear_update_issue.description` replaces the full issue body.
- `linear_edit_issue_description` supports append, prepend, and heading-section
replacement with optional hash and `updatedAt` checks.
- Known Linear API keys are redacted from error messages.
## Development
```bash
npm run dev
npm test
npm run typecheck
npm run build
npm run secrets:check
npm run verify
```
Use the bundled pre-push hook locally:
```bash
git config core.hooksPath .githooks
```
`npm run prepush` runs the secret scan, typecheck, tests, build, and a
high-severity npm audit.
## Project Layout
```text
src/index.ts stdio entry point
src/server.ts MCP tool registration and schemas
src/linear.ts Linear SDK adapters and compact summaries
src/env.ts profile, toolset, and read-only configuration
src/graphql.ts GraphQL operation validation and mutation guardrails
src/*.test.ts Vitest coverage for core behavior
scripts/ local automation scripts
```
## References
- [Model Context Protocol TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector)
- [Linear TypeScript SDK](https://linear.app/developers/sdk)
- [Linear GraphQL API](https://linear.app/developers/graphql)
- [Linear rate limits](https://linear.app/developers/rate-limiting)
