Linear Project — Claude Code MCP server: setup and overview
Manages Linear projects with strict scope gating and audit logging. Connects read-only GitHub evidence and local Obsidian notes to issues.
claude mcp add --env LINEAR_API_KEY=<LINEAR_API_KEY> --env LINEAR_ACCESS_TOKEN=<LINEAR_ACCESS_TOKEN> --env LINEAR_ALLOWED_ORGANIZATION_ID=<LINEAR_ALLOWED_ORGANIZATION_ID> --env LINEAR_ALLOWED_TEAM_IDS=<LINEAR_ALLOWED_TEAM_IDS> --env LINEAR_ALLOWED_PROJECT_IDS=<LINEAR_ALLOWED_PROJECT_IDS> --transport stdio linear-project-mcp-server -- npx -y @openly-useful/linear-project-mcp-serverWhat Linear Project does
The server enforces strict allowlists for organizations, teams, and projects before executing Linear operations. Identifiers attach to teams, not projects. Because of that rule, counter resets to 1 succeed only when verifying an empty dedicated team or subteam.
Write operations require MCP_WRITES_ENABLED=true, a literal confirmation flag, and an active window under 60 minutes. Optional adapters link external evidence. The GitHub integration runs GET queries against permitted repositories. The Obsidian adapter reads local Markdown notes under 200,000 bytes, sending only titles and URIs to Linear. Without an intact audit path outside the repo, write actions abort immediately.
What it helps with
- restrict agent actions to explicit Linear teams and scope codes
- prevent unauthorized mutations using timed 60-minute write windows
- attach GitHub pull request references to Linear tickets
- connect local Obsidian Markdown notes without leaking file bodies
Example prompts for the agent
- Inspect active scopes and allowlists with
linear_project_capabilities - Fetch issues under the ACQI scope using
linear_project_list_scoped_issues - Attach a local note URI to an issue via
linear_project_link_evidence
How to install Linear Project
Platform CLI
claude mcp add --env LINEAR_API_KEY=<LINEAR_API_KEY> --env LINEAR_ACCESS_TOKEN=<LINEAR_ACCESS_TOKEN> --env LINEAR_ALLOWED_ORGANIZATION_ID=<LINEAR_ALLOWED_ORGANIZATION_ID> --env LINEAR_ALLOWED_TEAM_IDS=<LINEAR_ALLOWED_TEAM_IDS> --env LINEAR_ALLOWED_PROJECT_IDS=<LINEAR_ALLOWED_PROJECT_IDS> --transport stdio linear-project-mcp-server -- npx -y @openly-useful/linear-project-mcp-serverReplace <…> with your own values. 9 more environment variables are in the server README
Platform CLI
codex mcp add linear-project-mcp-server --env LINEAR_API_KEY=<LINEAR_API_KEY> --env LINEAR_ACCESS_TOKEN=<LINEAR_ACCESS_TOKEN> --env LINEAR_ALLOWED_ORGANIZATION_ID=<LINEAR_ALLOWED_ORGANIZATION_ID> --env LINEAR_ALLOWED_TEAM_IDS=<LINEAR_ALLOWED_TEAM_IDS> --env LINEAR_ALLOWED_PROJECT_IDS=<LINEAR_ALLOWED_PROJECT_IDS> -- npx -y @openly-useful/linear-project-mcp-serverReplace <…> with your own values. 9 more environment variables are in the server README
Config file
{
"mcpServers": {
"linear-project-mcp-server": {
"command": "npx",
"args": [
"-y",
"@openly-useful/linear-project-mcp-server"
],
"env": {
"LINEAR_API_KEY": "<LINEAR_API_KEY>",
"LINEAR_ACCESS_TOKEN": "<LINEAR_ACCESS_TOKEN>",
"LINEAR_ALLOWED_ORGANIZATION_ID": "<LINEAR_ALLOWED_ORGANIZATION_ID>",
"LINEAR_ALLOWED_TEAM_IDS": "<LINEAR_ALLOWED_TEAM_IDS>",
"LINEAR_ALLOWED_PROJECT_IDS": "<LINEAR_ALLOWED_PROJECT_IDS>"
}
}
}
}Replace <…> with your own values. 9 more environment variables are in the server README
Config file
{
"servers": {
"linear-project-mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@openly-useful/linear-project-mcp-server"
],
"env": {
"LINEAR_API_KEY": "<LINEAR_API_KEY>",
"LINEAR_ACCESS_TOKEN": "<LINEAR_ACCESS_TOKEN>",
"LINEAR_ALLOWED_ORGANIZATION_ID": "<LINEAR_ALLOWED_ORGANIZATION_ID>",
"LINEAR_ALLOWED_TEAM_IDS": "<LINEAR_ALLOWED_TEAM_IDS>",
"LINEAR_ALLOWED_PROJECT_IDS": "<LINEAR_ALLOWED_PROJECT_IDS>"
}
}
}
}Replace <…> with your own values. 9 more environment variables are in the server README
Platform CLI
gemini mcp add -e LINEAR_API_KEY=<LINEAR_API_KEY> -e LINEAR_ACCESS_TOKEN=<LINEAR_ACCESS_TOKEN> -e LINEAR_ALLOWED_ORGANIZATION_ID=<LINEAR_ALLOWED_ORGANIZATION_ID> -e LINEAR_ALLOWED_TEAM_IDS=<LINEAR_ALLOWED_TEAM_IDS> -e LINEAR_ALLOWED_PROJECT_IDS=<LINEAR_ALLOWED_PROJECT_IDS> linear-project-mcp-server npx -y @openly-useful/linear-project-mcp-serverReplace <…> with your own values. 9 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Linear Project
How do I install Linear Project in Claude Code?
Run `claude mcp add linear-project -e LINEAR_API_KEY=<LINEAR_API_KEY> -e LINEAR_ACCESS_TOKEN=<LINEAR_ACCESS_TOKEN> -e LINEAR_ALLOWED_ORGANIZATION_ID=<LINEAR_ALLOWED_ORGANIZATION_ID> -e GITHUB_TOKEN=<GITHUB_TOKEN> -- npx -y @openly-useful/linear-project-mcp-server`.
What does Linear Project do?
It provides scope-gated administration of Linear projects and issues. The server also links external evidence from GitHub repositories and Obsidian vaults under strict allowlists.
What environment is required to run the server?
It requires Node.js 20 or newer alongside pnpm 10. Local Obsidian notes must stay under 200,000 bytes.
