dsh-linear-mcp

A stdio Model Context Protocol server for Linear, built for DeepSeek Harness (dsh), Codex, Claude and any other MCP client.

It authenticates with a Linear personal API key (lin_api_…) instead of OAuth, so it starts instantly and never needs a browser round-trip. That makes it a good fit for headless / ACP / Paseo-style agents where an OAuth-discovery bridge would race the session's tool snapshot.

• 22 tools: issues, sub-issues, relations, comments, projects, cycles, teams, users, labels, workflow states

• Plain JSON output, per-request timeout, no write tools without a key

• Zero runtime services: one Node process, stdio only

Tools

Issue results include creatorId and creator: { id, name, displayName, email }. The creator is the original issue reporter, independently of its current assignee. These fields are included in issue detail, lists, searches and issue mutation responses; both are null when Linear has no creator. A creator lookup error is reported as an error, so callers must not infer the reporter from an assignee or comment author.

Related MCP server: Linear MCP Server

Auth

Create a key in Linear → Settings → Account → Security & Access → Personal API keys, then export it:

export LINEAR_API_KEY="lin_api_xxxxxxxx"

The server sends the key as Authorization: <key> (personal API keys; OAuth tokens starting with anything else are sent as Bearer). It never logs the key.

Install

# from this repo (no npm publish required)
npm install --global github:arucil/dsh-linear-mcp

# or run without installing
npx --yes github:arucil/dsh-linear-mcp --help

Use with DeepSeek Harness (dsh)

1. Install the server into the profile you use (web, acp for Paseo, headless):

   dsh plugin --profile acp add github:arucil/dsh-linear-mcp

   This links dsh-linear-mcp into ~/.dsh/profiles/acp/node_modules/.bin/.

2. Mount it through the first-party MCP bridge by adding this to ~/.dsh/profiles/acp/cordis.patch.yml (see examples/dsh-cordis.patch.yml):

   - insert:
       - id: mcp-linear
         name: '@deepseek-ai/dsh-mcp-client'
         config:
           serverName: linear
           transport: stdio
           command: /home/USER/.dsh/profiles/acp/node_modules/.bin/dsh-linear-mcp
           env:
             LINEAR_API_KEY: !!js process.env.LINEAR_API_KEY
           toolCallTimeoutMs: 60000

3. Start a new session (bundle patches apply at startup). The model sees the tools as mcp__linear__<tool>.

Put LINEAR_API_KEY in the environment of the process that starts dsh (your shell, or the Paseo daemon). Do not commit it to the profile.

Use with Codex

[mcp_servers.linear-local]
command = "dsh-linear-mcp"
args = []
env = { LINEAR_API_KEY = "lin_api_xxxxxxxx" }

Use with Claude Code

claude mcp add linear -- dsh-linear-mcp
# then export LINEAR_API_KEY, or pass env in the client config

CLI

dsh-linear-mcp [--api-key <lin_api_...>] [--endpoint <url>] [--timeout-ms <n>]

LINEAR_API_KEY          required unless --api-key is passed
LINEAR_API_URL          optional GraphQL endpoint override
LINEAR_MCP_TIMEOUT_MS   optional per-request timeout (default 20000)

Development

npm install
npm run build      # tsc -> dist/
npm test           # builds, then runs the in-memory MCP smoke tests
npm run typecheck

The smoke tests drive the server over an in-memory MCP transport with a fake LinearService, so they need no network or API key.

Security

• Read/write over your own Linear permissions. Delete tools are marked destructive for clients that honor annotations.

• The API key stays in the process environment; the server never writes it to disk or logs it.

• Only https://api.linear.app/graphql is contacted unless you override LINEAR_API_URL.

License

MIT