# Quick Start Guide
Get up and running with MCP Linear.app server in 5 minutes.
## Prerequisites
- Bun 1.0.0+ installed (or Node.js 18+)
- Linear.app account
- An MCP client (such as Claude Desktop, Cline, or others)
## Step 1: Get Your Linear API Key
1. Go to https://linear.app/settings/api
2. Click **"Create new API key"**
3. Give it a name (e.g., "MCP Server")
4. Copy the API key (starts with `lin_api_`)
## Step 2: Install the Server
```bash
# Clone the repository
git clone <your-repo-url>
cd mcp-linearapp
# Install dependencies
bun install
# Build the project
bun run build
```
## Step 3: Configure Environment
Create a `.env` file in the project root:
```bash
LINEAR_API_KEY=lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
Replace `lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx` with your actual API key.
## Step 4: Configure Your MCP Client
Add the server configuration to your MCP client's configuration file. The exact location and format may vary by client.
**Example configuration:**
```json
{
"mcpServers": {
"linear": {
"command": "node",
"args": ["/absolute/path/to/mcp-linearapp/dist/index.js"],
"env": {
"LINEAR_API_KEY": "lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
}
}
```
**Platform-specific paths:**
- **macOS**: `/Users/yourusername/projects/mcp-linearapp/dist/index.js`
- **Windows**: `C:\\Users\\yourusername\\projects\\mcp-linearapp\\dist\\index.js`
- **Linux**: `/home/username/projects/mcp-linearapp/dist/index.js`
**Important:**
- Use absolute paths, not relative paths
- Replace the API key with your actual key
- Use forward slashes (/) on macOS/Linux
- Use double backslashes (\\) on Windows
## Step 5: Restart Your MCP Client
Close and reopen your MCP client completely for the changes to take effect.
## Step 6: Test the Integration
Try these commands in your MCP client:
### List Your Teams
```
List all Linear teams
```
You should see a response with your Linear teams.
### Create a Test Issue
```
Create a test issue in Linear titled "MCP Integration Test" in the [TEAM_NAME] team
```
Replace `[TEAM_NAME]` with one of your team names from the previous step.
### List Issues
```
List all issues in Linear for the [TEAM_NAME] team
```
You should see your newly created test issue!
## Common First Commands
### Explore Your Workspace
```
1. List all Linear teams
2. List all users in Linear
3. List all projects
4. List labels for team X
```
### Create Your First Issue
```
1. List teams to get team ID
2. Create an issue titled "Setup automation" in team X
3. List issues to confirm it was created
```
### Update an Issue
```
1. List issues to find the issue identifier (e.g., "ENG-123")
2. Update issue ENG-123 to set priority to high
3. Get details for ENG-123 to confirm the change
```
## Troubleshooting
### "Linear tools not showing up"
**Solutions:**
1. Verify the config file path is correct
2. Check that you've completely restarted your MCP client
3. Verify the path to `dist/index.js` is absolute
4. Check your MCP client's logs for errors
### "Invalid API key"
**Solutions:**
1. Verify you copied the entire API key
2. Check there are no extra spaces in the `.env` file
3. Make sure the key starts with `lin_api_`
4. Try generating a new API key
### "Command not found: node"
**Solutions:**
1. Verify Bun is installed: `bun --version` (or Node.js: `node --version`)
2. Use the full path to node: `which node` (macOS/Linux) or `where node` (Windows)
3. Update the config to use the full node path
### "Module not found"
**Solutions:**
1. Make sure you ran `bun install`
2. Make sure you ran `bun run build`
3. Check that `dist/` folder exists and contains `index.js`
### "Team not found" when creating issues
**Solutions:**
1. Run `List all Linear teams` to get valid team IDs
2. Use the exact team ID from the response
3. Make sure you have permission to create issues in that team
## Next Steps
### Learn More
- Read the [API Reference](./API_REFERENCE.md) for detailed tool documentation
- Check out [README.md](../README.md) for workflow examples
- Review [DEVELOPMENT.md](../DEVELOPMENT.md) for advanced usage
### Try These Workflows
**Daily Standup Preparation:**
```
1. List my assigned issues with status "started"
2. Get details for each issue
3. Add comments with today's progress
```
**Sprint Planning:**
```
1. Create a new 2-week cycle for team X
2. List backlog issues for team X
3. Update priority issues and assign to team members
4. Move issues to the sprint
```
**Bug Triage:**
```
1. Search for issues with "bug" label
2. List unassigned bugs
3. Create labels for bug categories if needed
4. Assign bugs to team members
5. Set priority levels
```
**Project Management:**
```
1. List all projects for team X
2. List issues for project Y
3. Check progress and update statuses
4. Add comments with status updates
```
## Tips for Success
### Use Natural Language
Most MCP clients understand natural commands. Instead of:
```
linear_list_issues with teamId abc-123 and status started
```
Just say:
```
Show me all in-progress issues for the Engineering team
```
### Chain Operations
You can ask for multiple operations:
```
List all teams, then show me the issues for the Engineering team
```
### Get Context First
Before creating or updating, list relevant items:
```
1. List teams (to get team IDs)
2. List users (to get assignee IDs)
3. List projects (to get project IDs)
4. Then create the issue
```
### Use Issue Identifiers
Instead of long IDs, use the short identifier:
```
Update issue ENG-123 to change priority
```
Not:
```
Update issue issue-abc-123-def-456-ghi to change priority
```
## Getting Help
If you run into issues:
1. Check the [Troubleshooting](#troubleshooting) section above
2. Review the [README](../README.md) for detailed documentation
3. Check your MCP client's logs for error messages
4. Verify your Linear API key has the necessary permissions
5. Test the API key directly at https://linear.app/settings/api
## Security Notes
- **Never commit your API key** to version control
- Keep your `.env` file private
- Use separate API keys for development and production
- Revoke API keys you're no longer using
- Consider using a dedicated Linear account for automation
## Success Checklist
- [ ] Bun 1.0.0+ installed (or Node.js 18+)
- [ ] Repository cloned and dependencies installed
- [ ] Project built successfully (`bun run build`)
- [ ] Linear API key obtained
- [ ] `.env` file created with API key
- [ ] MCP client config updated with absolute path
- [ ] MCP client restarted
- [ ] Teams list command works
- [ ] Test issue created successfully
If all items are checked, you're ready to use the Linear MCP server!
---
**Happy automating!** For more advanced usage, check out the complete [README](../README.md) and [API Reference](./API_REFERENCE.md).
