Registry / devops / linear-cache-mcp

linear-cache-mcp

library0.1.3jsnpmunverified

Cache-first MCP server for Linear that reduces API usage by serving reads from a local JSON cache while tracking request budgets. Version 0.1.3 supports read/write through the Model Context Protocol, with tools for listing issues, projects, and project updates. It requires Node >=20, uses ESM, and is designed for coding agent workflows (e.g., Pi) where rate limits are a concern. Unlike direct Linear API clients, it avoids exhausting rate limits by caching reads and only calling the Linear API for writes or cache misses.

devops productivity

npm install linear-cache-mcp

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LINEAR-CACHE-MCP

linear-cache-mcp

devopsjavascriptv0.1.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ npx -y linear-cache-mcp

✗ require('linear-cache-mcp')

Package is an MCP server, not a library. Run via npx or as a command. No programmatic import.

linear_cache_list_issues

✓ MCP tool provided by the server; call via MCP client (e.g., pi-mcp-adapter)

✗ import { linear_cache_list_issues } from 'linear-cache-mcp'

Tools are not exported as JavaScript symbols; they are MCP tools invoked over stdio.

linear_cache_create_issue

✓ MCP tool provided by the server; call via MCP client

✗ import { linear_cache_create_issue } from 'linear-cache-mcp'

Write tools are also MCP tools; cannot be imported.

Shows how to run the MCP server and smoke test it. Requires env vars for Linear API key and team ID.

npx -y linear-cache-mcp # Ensure LINEAR_API_KEY env var is set: export LINEAR_API_KEY='lin_api_...' export LINEAR_TEAM_ID='your-team-id' # To smoke test: npx -y linear-cache-mcp --stdio-smoke # Expected output: JSON with "ok": true

Debug

Known issues

gotchaNo programmatic Node.js API; package must be run as an MCP server via CLI.

fix

Use npx or node path/to/server.mjs from a clone. Do not attempt require() or import.

affects: >=0.0.0

deprecatedLinear Docs/Documents are not exposed; only Issues, Projects, and Project Updates are cached.

fix

Use official Linear API for documents, or contribute to the package to add support.

affects: >=0.0.0

gotchaCache freshness duration is not configurable; stale reads may return outdated data.

fix

Use liveRefresh: true parameter in list tools to force a live fetch for specific queries.

affects: 0.1.3

Errors

Common errors & fixes

Error: Cannot find module 'linear-cache-mcp'

Attempted to require() the package as a Node.js library.

fix

Run as CLI: npx -y linear-cache-mcp

Connection closed (Pi agent)

MCP server failed to start or crashed.

fix

First run 'npx -y linear-cache-mcp --stdio-smoke' to verify the package works. If smoke passes, restart Pi or run '/mcp reconnect linear-cache'.

LINEAR_API_KEY not set

Environment variable LINEAR_API_KEY is missing.

fix

Export the key before running: export LINEAR_API_KEY=lin_api_...

Upgrade

Version history

0.1.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ch-raph/linear-cache-mcp ↗

packagelinear-cache-mcp ↗

homepagehttps://github.com/ch-raph/linear-cache-mcp#readme ↗