README.md•5.83 kB
# Linear MCP Server
A Model Context Protocol (MCP) server implementation for the Linear GraphQL API that enables AI assistants to interact with Linear project management systems.
[](https://www.npmjs.com/package/@emmett.deen/linear-mcp-server)
[](https://smithery.ai/server/@emmett-deen/linear-mcp-server)
## Features
- Access to Linear's GraphQL API through MCP tools
- Authentication via Linear API key
- Retrieve and modify data related to users, teams, projects, and issues
- Create, update and comment on issues
- Add and remove labels
- Create projects
- Comprehensive documentation of available tools
## Installation
### Installing via Smithery (Recommended)
To install Linear MCP Server for Claude Desktop automatically via Smithery:
```bash
npx -y @smithery/cli install @emmett.deen/linear-mcp-server --client claude
```
### Manual Configuration
After installation, add the following to your MCP settings file:
```json
{
"mcpServers": {
"linear": {
"command": "npx",
"args": ["-y", "@emmett.deen/linear-mcp-server"],
"env": {
"LINEAR_API_KEY": "your_linear_api_key_here"
}
}
}
}
```
### Client-Specific Configuration Locations
- Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Claude VSCode Extension: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
- GoMCP: `~/.config/gomcp/config.yaml`
### Manual Installation
1. Clone the repository
```bash
git clone https://github.com/yourusername/Linear-MCP-Server.git
cd Linear-MCP-Server
```
2. Install dependencies
```bash
npm install
```
3. Build the project
```bash
npm run build
```
4. Create a `.env` file with your Linear API token
```
LINEAR_API_KEY=your_linear_api_key_here
```
5. Start the server
```bash
npm start
```
## Available Tools
See [TOOLS.md](TOOLS.md) for a complete list of available tools and planned features.
## Overview
Linear-MCP-Server bridges the gap between Claude (AI assistant) and Linear (project management tool) by implementing the MCP protocol. This allows Claude to:
- Retrieve issues, projects, teams, and other data from Linear
- Create and update issues
- Change issue status
- Assign issues to team members
- Add comments
- Create projects and teams
The server uses Linear's GraphQL API and authenticates via user tokens (not OAuth) for simplicity.
## Getting Started
### Prerequisites
- Node.js (v18+)
- NPM or Yarn
- Linear API token
### Installation
```bash
# Install globally
npm install -g @emmett.deen/linear-mcp-server
# Or clone and install locally
git clone https://github.com/yourusername/Linear-MCP-Server.git
cd Linear-MCP-Server
npm install
npm link # Makes the package available globally
```
### Running the Server
Run the server with your Linear API token:
```bash
linear-mcp-server --token YOUR_LINEAR_API_TOKEN
```
Or set the token in your environment and run without arguments:
```bash
export LINEAR_API_TOKEN=YOUR_LINEAR_API_TOKEN
linear-mcp-server
```
## Using with Claude Desktop
To use this MCP server with Claude Desktop:
1. Enable Developer Mode in Claude Desktop (from the menu bar)
2. Go to Settings > Developer options
3. Click "Add Server"
4. Configure with the following settings:
- **Name**: Linear MCP Server
- **Type**: Local Process
- **Command**: linear-mcp-server
- **Arguments**: --token YOUR_LINEAR_API_TOKEN
Alternatively, manually edit the config file:
```json
{
"mcp": {
"servers": [
{
"name": "Linear MCP Server",
"transport": {
"type": "stdio",
"command": "linear-mcp-server",
"args": ["--token", "YOUR_LINEAR_API_TOKEN"]
}
}
]
}
}
```
5. Save the config
6. Restart Claude Desktop (quit completely and reopen)
7. You should now see Linear MCP Server available as a tool in Claude
## Example Claude Prompts
Once connected to Claude Desktop, you can use prompts like:
- "Show me all my Linear issues"
- "Create a new issue titled 'Fix login bug' in the Frontend team"
- "Change the status of issue FE-123 to 'In Progress'"
- "Assign issue BE-456 to John Smith"
- "Add a comment to issue UI-789: 'This needs to be fixed by Friday'"
## Development
To develop locally:
```bash
# Clone the repository
git clone https://github.com/yourusername/Linear-MCP-Server.git
cd Linear-MCP-Server
# Install dependencies
npm install
# Run in development mode
npm run dev -- --token YOUR_LINEAR_API_TOKEN
```
### Extending the Server
To add new tools to the server:
1. Follow the implementation guide in the [TOOLS.md](./TOOLS.md) document
2. Make sure to follow the established code structure in the `src/` directory
3. Update the documentation to reflect your changes
## Developing and Contributing
### Setup Development Environment
1. Clone the repository
```bash
git clone https://github.com/yourusername/Linear-MCP-Server.git
cd Linear-MCP-Server
```
2. Install dependencies
```bash
npm install
```
3. Start in development mode
```bash
npm run dev
```
### Publishing to npm
To publish this package to npm:
1. Update the version in package.json
```bash
npm version patch # or minor, or major
```
2. Build the project
```bash
npm run build
```
3. Make sure you've already logged in to npm
```bash
npm login
```
4. Publish to npm
```bash
npm publish --access public
```
5. For Smithery registry, you'll need to work with the Smithery team to get your server listed in their catalog.
## License
This project is licensed under the MIT License - see the LICENSE file for details.