Content
# Linear MCP Server
> A Model Context Protocol (MCP) server for [Linear](https://linear.app) - fetch your assigned issues as markdown
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
[](https://www.typescriptlang.org/)
## Features
- 📋 **Get your assigned issues** - Fetch all issues assigned to you in Linear
- 🔍 **Filter by status** - Filter issues by status (Todo, In Progress, Done, etc.)
- 🏷️ **Filter by team** - Filter issues by team name
- 🔎 **Get specific issue** - Fetch a specific issue by ID
- 📝 **Markdown output** - All issues returned as formatted markdown
- 📄 **Export to file** - Export issues to markdown for AI agents to track
- 🎯 **Priority sorting** - Issues automatically sorted by priority
- ✅ **Full MCP compliance** - Properly implements the MCP protocol
## Installation
### Prerequisites
- Node.js >= 18.0.0
- A Linear account with an API key
### Get Linear API Key
1. Go to [Linear Settings > API](https://linear.app/settings)
2. Click "Create personal API key"
3. Give it a name (e.g., "MCP Server")
4. Copy the key (starts with `lin_api_`)
### Install Dependencies
```bash
cd linear-mcp
npm install
```
### Build
```bash
npm run build
```
## Setup
### For Claude Code
Add this to your Claude config (usually at `~/.config/claude-code/mcp_config.json`):
```json
{
"mcpServers": {
"linear": {
"command": "node",
"args": ["/path/to/linear-mcp/dist/index.js"],
"env": {
"LINEAR_API_KEY": "lin_api_your-key-here"
}
}
}
}
```
Replace `/path/to/linear-mcp/dist/index.js` with the actual absolute path.
### For Zed
Add to `~/.config/zed/settings.json`:
```json
{
"context_servers": {
"linear-mcp": {
"enabled": true,
"command": "node",
"args": ["/path/to/linear-mcp/dist/index.js"],
"env": {
"LINEAR_API_KEY": "lin_api_your-key-here"
}
}
}
}
```
### For Continue.dev
Add to `~/.continue/config.json`:
```json
{
"mcpServers": [
{
"command": "node",
"args": ["/path/to/linear-mcp/dist/index.js"],
"env": {
"LINEAR_API_KEY": "lin_api_your-key-here"
}
}
]
}
```
### For Cline (VS Code)
Add to your Cline settings:
```json
{
"mcpServers": [
{
"name": "linear",
"command": "node",
"args": ["/path/to/linear-mcp/dist/index.js"],
"env": {
"LINEAR_API_KEY": "lin_api_your-key-here"
}
}
]
}
```
## Testing
### Test API Connection
```bash
LINEAR_API_KEY=lin_api_your-key npm run test
```
### Test MCP Protocol
```bash
LINEAR_API_KEY=lin_api_your-key npm run test:mcp
```
This verifies the server correctly implements the MCP protocol by sending actual JSON-RPC messages.
## Usage
Once configured, you can ask your AI assistant to:
- "Show me my Linear issues"
- "What issues do I have in progress?"
- "Get my issues for the x team"
- "Show me issue XYZ-123"
### Available Tools
#### `get-my-issues`
Get all issues assigned to you.
**Parameters:**
- `status` (optional): Filter by status - "Backlog", "Todo", "In Progress", "Done", or "Canceled"
- `team` (optional): Filter by team name
**Example:**
```json
{
"name": "get-my-issues",
"arguments": {
"status": "In Progress",
"team": "Alphonse"
}
}
```
#### `get-issue-by-id`
Get a specific issue by its ID.
**Parameters:**
- `issueId` (required): The Linear issue ID (e.g., "LIN-123")
**Example:**
```json
{
"name": "get-issue-by-id",
"arguments": {
"issueId": "LIN-123"
}
}
```
#### `export-issues`
Export issues to a markdown file with AI agent todo lists for tracking progress. Issues are sorted by priority (highest first).
**Parameters:**
- `outputFile` (required): Path to the output markdown file
- `status` (optional): Filter by status - "Backlog", "Todo", "In Progress", "Done", or "Canceled"
- `team` (optional): Filter by team name
- `limit` (optional): Maximum number of issues to export (takes top N by priority)
**Examples:**
```json
{
"name": "export-issues",
"arguments": {
"outputFile": "./issues.md",
"team": "Alphonse",
"status": "Todo"
}
}
```
```json
{
"name": "export-issues",
"arguments": {
"outputFile": "./top-3-todo.md",
"status": "Todo",
"limit": 3
}
}
```
**Usage with AI agent:**
- "Export my Alphonse Todo issues to alphonse-todo.md"
- "Take the first 3 issues by priority into a todo file"
- "Create a todo with my top 5 high-priority issues"
```json
{
"name": "export-issues",
"arguments": {
"outputFile": "./issues.md",
"team": "Alphonse",
"status": "Todo"
}
}
```
This creates a markdown file with:
- Summary table with issue counts
- Overall progress tracker
- Each issue with AI agent todo checklist
- Sorted by priority
**Usage with AI agent:**
```
"Export my Alphonse Todo issues to ./alphonse-todo.md"
"Create a file with all my issues"
```
## Exporting Issues to a File
You can export your Linear issues to a markdown file that AI agents can use to track progress. This is useful for:
- Giving an AI agent a todo list of issues to work through
- Creating a snapshot of your current workload
- Generating reports or documentation
- Batch processing issues with AI
### Option 1: Use MCP Tool (Recommended)
Ask your AI assistant to export issues:
```
"Export my Alphonse team issues to alphonse-issues.md"
"Export all Todo issues to ./todo.md"
```
The AI agent will use the `export-issues` MCP tool directly.
### Option 2: CLI Tool
You can also run the export directly from the command line:
```bash
# Export all issues
LINEAR_API_KEY=lin_api_your-key npm run export -- my-issues.md
# Filter by team
LINEAR_API_KEY=lin_api_your-key npm run export -- alphonse-issues.md --team Alphonse
# Filter by status
LINEAR_API_KEY=lin_api_your-key npm run export -- todo-issues.md --status "Todo"
# Combine filters
LINEAR_API_KEY=lin_api_your-key npm run export -- alphonse-todo.md --team Alphonse --status "Todo"
```
### Exported File Format
# Sort by status
npm run export -- issues.md --status
# Sort by issue identifier
npm run export -- issues.md --identifier
```
### Exported File Format
The exported markdown file includes:
- Summary table with issue counts by status
- Overall progress tracker with checkboxes
- Each issue with:
- Status and priority indicators (emojis)
- Issue description
- Direct link to Linear
- AI Agent Todo checklist for tracking progress
Example output:
```markdown
# Linear Issues Export
**Generated:** 2025-02-02T12:00:00.000Z
**Total Issues:** 15
**Team:** Alphonse
## Summary
| Status | Count |
|--------|-------|
| Total | 15 |
| Todo | 8 |
| In Progress | 3 |
| Done | 4 |
## Issues
### 1. [ALP-76] Update footer social icons
📝 **Status:** Todo
🟠 **Priority:** High
**URL:** https://linear.app/...
**Description:** Update the footer...
#### AI Agent Todo
- [ ] **Review Issue:** Read and understand the requirements
- [ ] **Research:** Look up relevant documentation/examples
- [ ] **Implement:** Make the necessary code changes
- [ ] **Test:** Verify the implementation works
- [ ] **Update Status:** Mark as complete in Linear when done
---
```
### Using with AI Agents
Once exported, you can share the file with an AI agent:
```bash
# With Claude Code
claude "Please work through the issues in alphonse-issues.md"
# Or include in your project
cp alphonse-issues.md ./path/to/project/
```
The AI agent can then:
1. Read through the issues
2. Check off items as it completes them
3. Update the file with progress notes
4. Reference the direct links to Linear for more details
## Example Output
```markdown
# My Linear Issues
## LIN-42: Fix authentication bug
**Status:** In Progress
**Priority:** Urgent
**URL:** https://linear.app/team/issue/LIN-42
**Assignee:** John Doe (john@example.com)
**Project:** Q1 Sprint
**Team:** Backend
### Description
Users are unable to log in when using SSO.
**Labels:** bug, urgent, authentication
---
## LIN-41: Update documentation
**Status:** Todo
**Priority:** Low
**URL:** https://linear.app/team/issue/LIN-41
### Description
Add API documentation for new endpoints.
---
```
## Development
### Project Structure
```
linear-mcp/
├── src/
│ ├── index.ts # MCP server entry point
│ ├── linear.ts # Linear API client
│ ├── format.ts # Markdown formatting
│ ├── types.ts # TypeScript types
│ ├── test.ts # API connection test
│ └── test-mcp.ts # MCP protocol test
├── dist/ # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md
```
### Scripts
- `npm run build` - Compile TypeScript
- `npm run dev` - Build and run the server
- `npm run test` - Test API connection
- `npm run test:mcp` - Test MCP protocol
## Troubleshooting
### "LINEAR_API_KEY environment variable is required"
Make sure you've set the `LINEAR_API_KEY` in your MCP config's `env` section.
### "Linear API error: 401"
Your API key is invalid. Check that you copied it correctly from Linear settings.
### No issues returned
- Make sure you have issues assigned to you in Linear
- Check that your API key has the right permissions
- Try running `npm run test` to debug
### MCP server not found
- Make sure you've built the project with `npm run build`
- Check the path in your MCP config is correct (use absolute path)
- Restart your AI editor/IDE
## Security
### API Key Handling
- **Never commit API keys** to version control - use environment variables
- The `.gitignore` file excludes `.env` files
- API keys are only stored in memory during runtime
- Error messages are sanitized to prevent leakage of sensitive information
### Environment Variable Isolation
The test suite (`test-mcp.ts`) only passes necessary environment variables to child processes:
- `PATH` - For executable lookup
- `HOME` - For user directory access
- `LINEAR_API_KEY` - For Linear authentication
This prevents accidental leakage of other environment variables.
### Error Message Sanitization
- API error messages only include HTTP status codes, not full response bodies
- GraphQL errors only include error messages, not stack traces or internal details
- Error objects are never logged directly - only error messages
### Recommendations
1. **Rotate API keys regularly** - Generate new keys periodically in Linear
2. **Use separate keys** - Create different keys for different environments
3. **Monitor usage** - Check Linear's API usage dashboard for suspicious activity
4. **Principle of least privilege** - Only grant necessary permissions to API keys
### Reporting Security Issues
If you discover a security vulnerability, please email it to the repository owner privately before creating a public issue.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
MIT License - see [LICENSE](LICENSE) for details.
## Acknowledgments
- Built with [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- Uses [Linear GraphQL API](https://developers.linear.app/docs/graphql/overview)
---
Made with ❤️ for the Linear community
