Linear Project Management Data — MCP Server

Access Linear issue tracking, project management, team workflows, and cycle planning data through a standardized MCP (Model Context Protocol) interface. This Actor wraps the Linear API as an MCP server, enabling AI agents to read and write Linear data using natural tool calls — no API key handling in your code.

What does this Actor do?

This Actor spawns the linear-pp CLI binary as a subprocess and proxies HTTP JSON-RPC requests through Apify's standby infrastructure. It exposes 10 PPE-priced tools for common Linear operations: listing and creating issues, managing projects, querying teams and users, handling cycles, comments, and attachments. Ideal for AI agents that need programmatic access to Linear's project management data without direct API integration overhead.

Why use this Actor?

• Project management automation — Create issues, update status, manage projects via AI agent tool calls
• No API key in code — LINEAR_API_KEY stored as Apify secret, never exposed in requests
• PPE pricing — Pay per event ($0.03-$0.08 per tool call), no monthly commitment
• MCP protocol — Standard JSON-RPC 2.0 interface, works with any MCP-compatible AI client
• Apify infrastructure — Handles scaling, monitoring, and availability automatically

Features

• 10 PPE-priced tools covering issues, projects, teams, users, cycles, comments, attachments, and labels
• Read and write access — List, create, update operations across all Linear entities
• Filtering and pagination — Full Linear filter syntax support with cursor-based pagination
• Secure credential management — API keys stored as Apify secrets, never in request payloads
• Standby mode — Actor stays alive between requests for sub-second response times
• JSON-RPC 2.0 standard — Interoperable with Claude, Cursor, and other MCP-compatible clients
• Structured output — Results returned as JSON and pushed to Apify dataset for audit trails
• Community actor — Lightweight wrapper around Linear's official API, no vendor lock-in

Quick Start

# 1. Set your Linear API key as an Apify secret
apify secrets:set LINEAR_API_KEY "lin_api_..."

# 2. Push the Actor to Apify
apify push

# 3. Run in standby mode
apify run

# 4. Configure your MCP client to connect

MCP client configuration:

{
  "mcpServers": {
    "linear": {
      "transport": "http",
      "url": "https://<actor-id>.acts.apify.net/mcp"
    }
  }
}

Example tool call to list issues:

{
  "tool": "issues_list",
  "args": {
    "filter": { "teamId": "TEAM_ID" },
    "first": 20
  }
}

Input

Field	Type	Description
tool	string	Linear tool to call (see MCP Tools Reference below)
args	object	Tool arguments as key-value pairs

Example input:

{
  "tool": "issues_list",
  "args": { "filter": { "teamId": "TEAM_ID" }, "first": 10 }
}

Output

The Actor returns JSON with the tool result:

{
  "success": true,
  "result": { ... }
}

Results are also pushed to the default dataset as an array of objects containing result, tool, and timestamp.

Tools

Tool	Description	PPE Price
issues_list	List issues with filtering and pagination	$0.05
issues_create	Create a new issue	$0.08
projects_list	List all projects	$0.05
projects_create	Create a new project	$0.08
teams_list	List all teams	$0.03
users_list	List workspace users	$0.03
comments_create	Create a comment on an issue	$0.05
attachments_create	Upload an attachment	$0.05
cycles_list	List all cycles	$0.05
labels_list	List all labels	$0.03

Pricing

PPE (Pay Per Event) pricing per tool call:

• Read operations (list, users, teams, cycles, labels): $0.03-$0.05
• Write operations (create, update): $0.05-$0.08

Example: 100 issue list calls = ~$5.00. No base fee, no monthly minimum.

Operation Type	Tools	Price Range
Read (list queries)	issues_list, projects_list, teams_list, users_list, cycles_list, labels_list	$0.03 - $0.05
Write (create/update)	issues_create, projects_create, comments_create, attachments_create	$0.05 - $0.08

Troubleshooting

Q: Do I need a Linear API key? A: Yes. Create one at Linear Settings > API. Store it as LINEAR_API_KEY in Apify secrets using apify secrets:set LINEAR_API_KEY "your_key".

Q: The Actor fails to start with "binary not found" A: Ensure the Dockerfile's go install step completed successfully. The binary path inside the container is /root/go/bin/linear-pp. Run apify build locally to verify.

Q: How do I filter issues by team or assignee? A: Use the filter param with Linear's filter syntax: { "teamId": "TEAM_ID", "assigneeId": "USER_ID" }. Refer to Linear's API docs for full filter options.

Q: What's the difference between this and the Linear REST API? A: This Actor wraps Linear's PP (Printing Press) CLI which provides a higher-level tool interface via MCP protocol. Direct REST API access is also available on Apify.

Q: Can I run this locally? A: Yes. Set APIFY_META_ORIGIN=STANDBY to activate standby mode, then run apify run. The Actor will stay alive between requests for faster response times.

Q: How does pagination work? A: Use the first/after cursor pattern for large result sets. Pass the after cursor from a previous response to fetch the next page of results.

FAQ

Q: What happens if the binary isn't installed? A: The Actor will fail to start. Ensure the Dockerfile's go install step completes successfully before pushing.

Q: Is my Linear API key secure? A: Yes. The LINEAR_API_KEY is stored as an Apify secret and only exposed to the Actor's runtime environment. It is never included in request payloads or logs.

Disclaimer

This Actor is a community project and not officially affiliated with Linear. Use of Linear's API is subject to Linear's terms of service.

Support

For issues or feature requests, open an issue on the GitHub repository.