Linear MCP Actor 🚀

The Linear MCP Actor is a powerful bridge between the Model Context Protocol (MCP) and Linear, the issue tracking tool. It empowers AI agents (like Claude, ChatGPT), automated workflows, and developers to interact directly with your Linear workspace to create issues, fetch data, and manage projects programmatically.

✨ Features

• AI-Ready: Designed to be used as a "Tool" for AI agents via Apify's MCP Server.
• Core Actions:
  • createIssue: Create new bugs, tasks, or features.
  • getIssue: Retrieve detailed information about a specific issue.
  • searchIssues: Find issues using flexible queries.
  • getViewer: Get details about the authenticated user (useful for health checks).
  • getTeam: Fetch team details.
• Secure: Uses your personal Linear API Key.

🛠️ Input Parameters

The actor accepts the following input fields:

Field	Type	Required	Description
apiKey	String	Yes	Your Linear Personal API Key (lin_api_...).
action	String	Yes	The operation to perform (e.g., createIssue).
payload	Object	No	Parameters for the chosen action (e.g., { title: "New Bug" }).

📖 Usage Examples

1. Check Connection (Health Check)

Action: getViewer Payload: {}

{
  "apiKey": "lin_api_YOUR_KEY",
  "action": "getViewer",
  "payload": {}
}

2. Create a New Issue

Action: createIssue

{
  "apiKey": "lin_api_YOUR_KEY",
  "action": "createIssue",
  "payload": {
    "teamId": "TEAM_ID",
    "title": "Fix login page crash",
    "description": "The login page crashes on clicking submit."
  }
}

3. Search for Isubes

Action: searchIssues

{
  "apiKey": "lin_api_YOUR_KEY",
  "action": "searchIssues",
  "payload": {
    "query": "bug",
    "first": 5
  }
}

4. Update an Issue (Agentic)

Action: updateIssue

{
  "apiKey": "...",
  "action": "updateIssue",
  "payload": {
    "id": "ISS-123",
    "input": {
      "priority": 1,
      "stateId": "done-state-id"
    }
  }
}

5. Comment on an Issue

Action: createComment

{
  "apiKey": "...",
  "action": "createComment",
  "payload": {
    "issueId": "ISS-123",
    "body": "Fix deployed to staging. @qa please verify."
  }
}

6. Read Issue Comments (Context)

Action: getComments

{
  "apiKey": "...",
  "action": "getComments",
  "payload": {
    "issueId": "ISS-123"
  }
}

🤖 How to Use with AI (MCP)

This actor is built to power AI agents. When connected via the Apify MCP Server:

1. The AI discovers this actor as a tool.
2. You prompt the AI: "Create a ticket in Linear for the database bug."
3. The AI calls this actor with createIssue, and the ticket is created automatically!

7. Get Workspace Metadata (The Brain 🧠)

Action: getWorkspaceMetadata Description: Fetches all Teams, Workflow States (IDs), and Labels. Crucial for AI agents to map human names (like "Done") to Linear IDs.

{
  "apiKey": "...",
  "action": "getWorkspaceMetadata",
  "payload": {}
}

8. Register Webhook (Automation ⚡)

Action: registerWebhook Description: Programmatically register a webhook for issue events.

{
  "apiKey": "...",
  "action": "registerWebhook",
  "payload": {
    "url": "https://your-webhook-endpoint.com/hook",
    "resourceTypes": ["Issue", "Comment"]
  }
}

9. Advanced Issue Search

Action: searchIssues Description: Use filters to narrow down results.

{
  "apiKey": "...",
  "action": "searchIssues",
  "payload": {
    "query": "login bug",
    "filter": {
      "stateId": "state-id-for-todo",
      "priority": 1
    }
  }
}

🧠 Why this is an "Agentic" Actor?

1. Self-Discovery: The getWorkspaceMetadata action allows the AI to "learn" your Linear setup (Team IDs, Status IDs) without you manually hardcoding them.
2. Full Logic: It supports creating, updating, commenting, and reading issues, enabling full lifecycle management.
3. Error Handling: Returns structured error messages so the AI can correct its own mistakes (e.g., retrying with a valid ID).

📦 Integration (Node.js)

You can also use this in your own Node.js applications using the Apify Client:

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'MY_APIFY_TOKEN' });

const run = await client.actor('crickbossofficial-dot/linear-mcp-actor').call({
    apiKey: 'lin_api_...',
    action: 'getViewer',
});

console.log('Results:', run.defaultDatasetId);

🔒 Security

• API Key: Never hardcode your API key in public code. Use Apify's secret inputs or environment variables.
• The apiKey input is marked as sensitive in the schema to protect it in the Apify Console.

---

Built with ❤️ for the Agentic AI Future.