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