linear-local-mcp

MCP server for fast, local-only access to Linear data via the Linear.app macOS cache.

What it does

This MCP server reads Linear's local IndexedDB cache directly, providing instant access to your Linear data without API calls. Perfect for quickly browsing issues, searching, and getting context about your team's work.

Performance: Load ~24,000 issues in under 1 second vs. multiple API round-trips.

Requirements

• macOS (Linear.app stores its cache at ~/Library/Application Support/Linear/)
• Python 3.10+
• Linear.app installed and logged in (to populate the local cache)

Installation

Using uvx (recommended)

uvx linear-local-mcp

Using pipx

pipx run linear-local-mcp

From source

git clone --recursive https://github.com/gyfis/linear-local-mcp
cd linear-local-mcp
uv run linear-local-mcp

Claude Desktop Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "linear-local": {
      "command": "uvx",
      "args": ["linear-local-mcp"]
    }
  }
}

Available Tools

Tool	Description
list_issues	List issues with filters (assignee, team, state_type, priority, updated_after). Paginated.
get_issue	Get a single issue by identifier (e.g., T-1234)
search_issues	Search issues by title. Paginated.
list_users	List all users with issue counts
get_user	Get a user by name
list_teams	List all teams with issue counts
list_states	List workflow states
get_my_issues	Get issues for a user with counts by state type. Supports updated_after filter. Paginated.
get_summary	Get counts of teams, users, states, and issues

Filtering by Date

The list_issues and get_my_issues tools support an updated_after parameter to filter issues by last update time:

list_issues(updated_after="2024-01-01T00:00:00Z")
get_my_issues(name="me", updated_after="2024-12-25T00:00:00Z")

This accepts ISO-8601 datetime strings.

Pagination

Tools that return large result sets (list_issues, search_issues, get_my_issues) support cursor-based pagination:

• Pass limit to control page size (default 50, max 100)
• Response includes nextCursor if there are more results
• Pass cursor parameter with the nextCursor value to get the next page

Example flow:

1. Call list_issues(assignee="me", limit=20) → returns first 20 issues + nextCursor
2. Call list_issues(assignee="me", limit=20, cursor="abc123") → returns next 20 issues

Example Usage

Once configured, you can ask Claude:

• "What issues are assigned to me?"
• "Show me high priority bugs in the T team"
• "Search for issues about authentication"
• "Who has the most open issues?"

Limitations

• macOS only - Reads the Linear.app local cache
• Read-only - Cannot create or update issues (use the official Linear MCP for that)
• Data freshness - Data is only as fresh as Linear.app's last sync
• Cache TTL - Data is cached for 5 minutes before reloading from disk

How it works

Linear.app (an Electron app) stores a local cache of your Linear data in IndexedDB, which is backed by LevelDB on disk. This MCP server uses ccl_chromium_reader to read Chrome/Electron's IndexedDB format directly.

The server auto-detects Linear's internal object store structure by sampling records, so it should continue working even if Linear updates their schema.

Comparison with Official Linear MCP

Feature	linear-local-mcp	Official Linear MCP
Speed	Instant (local)	Network latency
Read issues	Yes	Yes
Create/update issues	No	Yes
Requires API key	No	Yes
Works offline	Yes	No
Data freshness	Last Linear.app sync	Real-time

Use this for fast reads; use the official Linear MCP when you need to make changes.

License

MIT