What the Linear Project MCP server does
The Linear Project MCP server turns three project-management workflows into typed MCP operations: bootstrapping a new project, synchronizing implementation work, and reconciling an existing project with legacy records. It can create a dedicated Linear team or subteam, establish a scope-labeled project, capture active or historical issues, move reviewed reconciliation candidates, and attach verified evidence.
The workflow is deliberately scope-limited. A canonical destination is resolved before writes occur, and unrelated teams, projects, labels, repositories, or source containers are not included. Historical records are marked separately with a [HISTORICAL] prefix and metadata indicating that they are not current actionable work.
How it works
The Linear Project MCP server communicates directly with Linear through the official TypeScript SDK. Its three workflows hand work to one another: a new project can be bootstrapped and then synchronized, while existing work can be reconciled before synchronization begins.
Linear issue identifiers belong to teams rather than projects or labels. Consequently, a workflow that requires a new issue sequence must provision a team with the requested key, verify that its issue history is empty, and read back the first created issue. The server stops when that guarantee cannot be established instead of treating a project label as a substitute.
Optional evidence adapters extend the source set without changing the main workflow. GitHub access is read-only. Obsidian access is local, limited to allowlisted Markdown directories, and links to notes without copying their contents into Linear.
Setup and configuration
For a source checkout, use Node.js 20 or newer, install the package dependencies with the repository's frozen lockfile, build the server, and register the resulting dist/index.js executable with Codex under the linear_project alias. The repository also documents an npm-based configuration for after the first package release.
Credentials must be provided through the host environment, a protected launcher, or a secret store rather than command arguments or committed client configuration. Linear authentication can use LINEAR_API_KEY or LINEAR_ACCESS_TOKEN.
The server can start without those settings, but writes remain disabled and Linear operations fail closed with configuration guidance. A connected Linear integration needs permission to read the target workspace and perform requested changes. Creating a team or team key may also require workspace administrator access.
Tools and capabilities
The Linear Project MCP server exposes 13 typed MCP tools covering these operations:
- Create a dedicated team or subteam and bootstrap a scoped project.
- Establish project and issue context for a new workstream.
- Capture active issues or deterministic historical records idempotently.
- Find existing projects and review reconciliation candidates.
- Move only explicitly reviewed, high-confidence issues.
- Link verified repository or local-note evidence.
- Keep project status, blockers, implementation evidence, and backlog gaps current.
The repository also contains three Agent Skills that use the same division of responsibilities: linear-bootstrap-scoped-project, linear-sync-project-work, and linear-reconcile-project-history. These skills are separate from the optional MCP server but describe the workflows it implements.
Limitations and notes
All mutations are disabled by default. Enabling a write requires an exact organization allowlist, scope-code allowlist, team and project gates, and literal confirmation for the individual tool. Fuzzy matches provide review evidence only; they do not authorize moving work.
The server does not include credentials, run as a background monitor, or mutate unrelated projects. GitHub support is optional and read-only, while Obsidian support is optional and local. The package requires Node.js 20 or newer. The repository material identifies the npm package and executable names, but does not establish a released package version beyond the registration example or provide a software license.