Linear MCP Server

# Linear MCP Server This is a Model Context Protocol (MCP) server for Linear, allowing Claude to interact with Linear's API to manage teams, issues, projects, and cycles. [](https://github.com/cpropster/linear-mcp-server) ## Features - **linear_get_teams**: Get all teams with their states and labels - **linear_search_issues**: Search for issues with filtering and pagination - **linear_get_cycles**: Get all cycles for a team - **linear_get_projects**: Get all projects - **linear_create_issue**: Create a new issue - **linear_update_issue**: Update an existing issue ## Quick Start For Cline MCP Marketplace users: 1. **Install the server** through the Cline MCP Marketplace 2. **Configure your Linear credentials** in the MCP configuration file 3. **Verify the installation** by testing the connection with `linear_search_issues` See the detailed [Installation](#installation) and [Verification](#verifying-installation) sections below. ## Installation 1. Clone this repository 2. Install dependencies: ```bash npm install ``` 3. Build the server: ```bash npm run build ``` The installation process has three main steps: 1. **Setup**: Clone and build the server (steps above) 2. **Configuration**: Set up your Linear OAuth token and configure the MCP server 3. **Verification**: Test the connection to ensure it's working properly ⚠️ **Your installation is not complete until you've verified the connection works!** ## Configuration The server requires a Linear OAuth token to authenticate with the Linear API. You can set this token in the MCP configuration file. ### Getting a Linear OAuth Token 1. Create a Linear OAuth application at https://linear.app/settings/api/applications 2. Create an OAuth Application 3. Name the Application Cline MCP 4. Set the redirect URI to `http://localhost:3000/callback` 5. Note the client ID and client secret 6. Create and Copy a USER based developer token ### MCP Configuration Add the following to your MCP configuration file: ```json { "mcpServers": { "github.com/cpropster/linear-mcp-server": { "command": "node", "args": [ "/path/to/linear-mcp-server/build/index.js" ], "env": { "LINEAR_CLIENT_ID": "your-client-id", "LINEAR_CLIENT_SECRET": "your-client-secret", "LINEAR_REDIRECT_URI": "http://localhost:3000/callback", "LINEAR_REFRESH_TOKEN": "your-refresh-token" }, "disabled": false, "autoApprove": [] } } } ``` Replace the placeholder credentials with your actual credentials. ### Verifying Installation ⚠️ **IMPORTANT**: Your installation is not complete until you verify that the MCP connection is working correctly. After configuring the MCP server, you must test the connection to ensure it's working properly: 1. Reload the MCP configuration 2. Test the connection by using the `linear_search_issues` tool: ``` use_mcp_tool( server_name="github.com/cpropster/linear-mcp-server", tool_name="linear_search_issues", arguments={ "first": 5 } ) ``` If successful, you'll see a response like this: ```json { "issues": { "nodes": [ { "id": "123abc", "title": "Example issue 1", "identifier": "TEAM-123", "description": "This is an example issue" // ... other issue data }, // ... more issues ] } } ``` If the connection is working, you'll see a list of issues from your Linear account. If you see an error, check your configuration and credentials. Common issues: - Incorrect server path in the `args` field - Invalid or expired Linear tokens - Missing required environment variables - Server is disabled in the configuration ## Usage ### Getting Teams Use the `linear_get_teams` tool to retrieve all teams: ``` use_mcp_tool( server_name="github.com/cpropster/linear-mcp-server", tool_name="linear_get_teams", arguments={} ) ``` ### Searching Issues Use the `linear_search_issues` tool to search for issues: ``` use_mcp_tool( server_name="github.com/cpropster/linear-mcp-server", tool_name="linear_search_issues", arguments={ "query": "Optional search query", "teamIds": ["Optional team IDs"], "first": 10 // Number of issues to return (default: 50) } ) ``` ### Getting Cycles Use the `linear_get_cycles` tool to retrieve cycles for a team: ``` use_mcp_tool( server_name="github.com/cpropster/linear-mcp-server", tool_name="linear_get_cycles", arguments={ "teamId": "required-team-id" } ) ``` ### Getting Projects Use the `linear_get_projects` tool to retrieve projects: ``` use_mcp_tool( server_name="github.com/cpropster/linear-mcp-server", tool_name="linear_get_projects", arguments={ "teamId": "optional-team-id", "first": 10 // Number of projects to return (default: 50) } ) ``` ### Creating Issues Use the `linear_create_issue` tool to create a new issue: ``` use_mcp_tool( server_name="github.com/cpropster/linear-mcp-server", tool_name="linear_create_issue", arguments={ "teamId": "required-team-id", "title": "Required issue title", "description": "Optional issue description", "assigneeId": "optional-assignee-id", "stateId": "optional-state-id", "priority": 0, // Optional priority (0-4) "estimate": 1, // Optional estimate "cycleId": "optional-cycle-id", "projectId": "optional-project-id", "labelIds": ["optional-label-ids"] } ) ``` ### Updating Issues Use the `linear_update_issue` tool to update an existing issue: ``` use_mcp_tool( server_name="github.com/cpropster/linear-mcp-server", tool_name="linear_update_issue", arguments={ "issueId": "required-issue-id", "title": "Optional new title", "description": "Optional new description", "assigneeId": "optional-assignee-id", "stateId": "optional-state-id", "priority": 0, // Optional priority (0-4) "estimate": 1, // Optional estimate "cycleId": "optional-cycle-id", "projectId": "optional-project-id", "labelIds": ["optional-label-ids"] } ) ``` ## Debugging If you encounter issues during the [verification step](#verifying-installation), or if the MCP connection stops working, you can use these debugging techniques: 1. **Check MCP Configuration**: Ensure your MCP configuration file has the correct server path and credentials. 2. **Run the Test Client**: Use the included test client to verify the server can connect to Linear: ```bash node test-client.js ``` This will run a series of tests to verify that the server can connect to Linear and retrieve data. 3. **Check Linear API Status**: Verify that the Linear API is operational at [status.linear.app](https://status.linear.app). 4. **Inspect Server Logs**: If you're running the server manually, check the console output for error messages. ## Development The server is built using TypeScript and the Linear SDK. The main implementation is in `src/index.ts`. To make changes to the server: 1. Edit the source code in `src/` 2. Build the server with `npm run build` 3. Test your changes with the test client 4. Update the MCP configuration to use the new build ## Security Considerations This MCP server requires access to your Linear account. To keep your data secure: 1. **Never commit sensitive tokens**: The `.env` file and any files containing tokens are excluded in `.gitignore` 2. **Use environment variables**: Always use environment variables in the MCP configuration rather than hardcoding tokens 3. **Limit permissions**: When creating a Linear OAuth application, only grant the permissions needed 4. **Regularly rotate tokens**: Periodically generate new tokens and update your configuration The server uses the official Linear SDK and communicates with Linear's API over HTTPS, ensuring your data is transmitted securely. ## License MIT