Model Context Protocol (MCP) servers enable Claude Code to directly interact with Linear and Notion for automated project management and documentation.
What is MCP? MCP (Model Context Protocol) allows Claude Code to connect to external services like Linear and Notion, enabling it to:
Create and update Linear tasks automatically
Sync project progress to Notion
Link GitHub commits/PRs to Linear issues
Generate milestone documentation
Linear MCP Setup Linear is our primary project tracking tool for day-to-day task management.
Workspace: https://linear.app/workally/projects/all Installation
Usage
Automation
Step 1: Get Linear API Key
Create API Key
Click “Create new personal API key”
Name: Claude Code MCP
Description: For automated task tracking via Claude Code
Click “Create key”
Copy API Key
Copy the key immediately - it starts with lin_api_You won’t be able to see it again after closing the dialog.
Add Linear MCP to your Claude Code configuration file. Config location: ~/.claude/config.toml[ mcp_servers . linear ] command = "npx" args = [ "-y" , "@modelcontextprotocol/server-linear" ] env = { LINEAR_API_KEY = "lin_api_YOUR_KEY_HERE" }
Replace lin_api_YOUR_KEY_HERE with your actual API key. Step 3: Restart Claude Code # Reload MCP servers claude --reload-mcp
Step 4: Verify Connection Test the connection by asking Claude Code: "Check if Linear MCP is connected and list my Linear teams"
Expected response: Claude lists your Linear teams and workspaces.Creating Projects from plan.md After creating your brief/plan.md, initialize Linear tracking: "Read brief/plan.md and create a new Linear project called '[Your Project Name]'. Create milestones for each phase and convert all tasks to Linear issues with appropriate labels (phase-0, phase-1, etc.)."
Claude Code will:
Create Linear project
Add milestones (Phase 0, Phase 1, etc.)
Create issues for each task
Add labels and priorities
Set due dates based on phase timing
Daily Progress Updates Update after completing tasks: "I just finished implementing user authentication. Update Linear issue WOR-123 to 'Done' and add completion notes."
End-of-day sync: "Review plan.md and update Linear with today's progress. Mark completed tasks as done and add notes to in-progress issues."
Creating New Issues Bug reports: "Found a bug in login validation. Create a Linear issue with priority High, label 'bug', and assign to current sprint."
Feature requests: "Create a Linear issue for adding Google OAuth with label 'enhancement' and add it to Phase 2 milestone."
PR & Commit Linking Link PRs to Linear: "I just created PR #23 for user authentication. Update Linear issue WOR-123 with the PR link and move to 'In Review'."
Commit message format: git commit -m "feat: Add user login Implements email/password authentication. Fixes WOR-123"
Linear will automatically link this commit to issue WOR-123. Git Hooks for Auto-Updates Automatically update Linear on every commit: Create post-commit hook: # Create hook file touch .git/hooks/post-commit chmod +x .git/hooks/post-commit # Edit file nano .git/hooks/post-commit
Add this content: #!/bin/bash COMMIT_MSG = $( git log -1 --pretty=%B ) claude "Update Linear with this commit: $COMMIT_MSG "
Result: Every commit automatically updates the linked Linear issue.Periodic Sync Schedule Daily:
End of workday: Sync all active issues
Mark completed tasks as done
Update time estimates
Weekly:
Review milestone progress
Adjust priorities
Update sprint planning
Per Phase:
Close phase milestone
Create phase completion summary
Plan next phase tasks
Notion MCP Setup Notion is used for major milestone documentation - not daily tracking.
Workspace: https://www.notion.so/workally/ Installation
Usage
Templates
Step 1: Create Notion Integration
Create New Integration
Click ”+ New integration”
Name: Claude Code MCPAssociated workspace: Select “WorkAlly”Type: Internal integrationClick “Submit”
Copy Integration Token
Copy the Internal Integration Token It starts with secret_
Get Database ID
Open your Notion project database
Copy URL - looks like:
https://notion.so/workally/1234567890abcdef1234567890abcdef
The database ID is: 1234567890abcdef1234567890abcdef
Share Database with Integration
Open your Notion project database
Click “Share” button (top right)
Click “Invite”
Search for “Claude Code MCP”
Grant Can edit permission
Click “Invite”
Add Notion MCP to ~/.claude/config.toml: [ mcp_servers . notion ] command = "npx" args = [ "-y" , "@modelcontextprotocol/server-notion" ] env = { NOTION_API_KEY = "secret_YOUR_TOKEN_HERE" }
Replace secret_YOUR_TOKEN_HERE with your integration token. Step 3: Restart Claude Code Same as Linear - reload MCP servers. Step 4: Verify Connection "Check Notion MCP connection and list my Notion databases"
When to Update Notion ✅ Update Notion for:
Phase completions (Phase 0 done, Phase 1 done, etc.)
MVP launch
Production deployment
Major feature releases
Quarterly reviews
❌ Do NOT update Notion for:
Individual task completions
Daily progress
Bug fixes
Minor updates
Phase Completion Documentation When you complete a phase: "Phase 1 (Authentication) is complete. Create a Notion page in the [Project Name] database documenting: - Title: 'Phase 1: Authentication Complete - [Date]' - Summary of implemented features - Screenshots or demo links - Deployment URL (staging/production) - Performance metrics - Known issues or limitations - Next steps (Phase 2 preview)"
MVP Launch Documentation "MVP is ready for launch! Create a comprehensive Notion launch page with: - Executive summary - Feature list with screenshots - Technical architecture diagram - Deployment details - Monitoring setup - User onboarding guide - Support documentation - Post-launch roadmap"
Production Deployment Report "App deployed to production! Document in Notion: - Deployment timestamp - Production URL - Environment variables checklist - Database migration status - Monitoring dashboard links - Incident response plan - Rollback procedure - Success metrics baseline"
Phase Completion Template Ask Claude Code to use this structure: # Phase [ X ]: [Phase Name] Complete **Completion Date:** [ Date ] **Duration:** [X weeks/days] **Status:** ✅ Complete ## Implemented Features - [Feature 1] - [Brief description] - [Feature 2] - [Brief description] ## Technical Details - Framework: Next.js 14 - Database: Supabase PostgreSQL - Authentication: Supabase Auth - Deployment: Vercel ## Metrics - Performance: [Lighthouse scores] - Test Coverage: [ X% ] - Bundle Size: [X KB] ## Screenshots [Add screenshots or demo video] ## Deployment - Staging: [ URL ] - Production: [URL if deployed] ## Known Issues - [Issue 1] - [Issue 2] ## Next Steps - Phase [ X+1 ] preview - Priorities for next phase
Milestone Template # Milestone: [ Name ] **Achievement Date:** [ Date ] **Impact:** [ High/Medium/Low ] ## What We Built [Summary paragraph] ## Key Features 1. [Feature with description] 2. [Feature with description] ## By the Numbers - Users: [ X ] - Performance: [ metrics ] - Uptime: [ % ] ## Challenges Overcome - [Challenge 1 and solution] ## Learnings - [Key learning 1] ## Next Milestone [What's coming next]
Complete Workflow Integration Step-by-Step: New Project Setup
Create Project Brief
mkdir brief cd brief # Create claude.md and plan.md
Initialize Linear Project
"Read brief/plan.md and create a Linear project with all phases and tasks"
Start Development
Begin working on Phase 0 tasks from Linear
Daily Updates
"Update Linear with today's completed tasks"
Complete Phase
"Phase 0 complete! Update Linear milestone and create Notion documentation"
Continue Cycle
Repeat for each phase, updating Linear daily and Notion per major milestone
Recommended Update Schedule Frequency Action Tool Per Task Mark task complete Linear Daily Sync progress, update estimates Linear Per PR Link PR to issue Linear + GitHub Per Phase Document completion Linear + Notion Per Milestone Create comprehensive doc Notion
Troubleshooting
Check config: cat ~/.claude/config.toml | grep -A 3 linear
Verify API key is valid: curl -H "Authorization: Bearer lin_api_YOUR_KEY" \ -H "Content-Type: application/json" \ https://api.linear.app/graphql \ -d '{"query": "{ viewer { name } }"}'
Reinstall MCP server: npx @modelcontextprotocol/server-linear --version
Notion MCP Not Connecting
Verify database sharing:
Open Notion database
Check “Claude Code MCP” integration has access
Ensure permission is “Can edit”
Test API token: curl -H "Authorization: Bearer secret_YOUR_TOKEN" \ -H "Notion-Version: 2022-06-28" \ https://api.notion.com/v1/users/me
Reload MCP servers: "Reload all MCP servers and verify connections"
Check Claude Code logs: cat ~/.claude/logs/mcp.log
Restart Claude Code completely: # Kill all Claude processes pkill -f claude # Restart claude
Best Practices
Linear Best Practices ✅ DO:
Update Linear after each task
Use consistent issue naming
Link all PRs to issues
Use labels and milestones
Add time estimates
❌ DON’T:
Create duplicate issues
Skip linking commits
Forget to close completed issues
Leave issues without assignees
Notion Best Practices ✅ DO:
Document major milestones only
Include screenshots and demos
Add deployment links
Track key metrics
Link to Linear issues
❌ DON’T:
Document every small task
Create pages for bugs
Duplicate Linear info
Skip technical details
Next Step With MCP configured, start your first project with the discovery phase →
