Orchid MCP Server

Connect Claude Code to your Orchid project boards. This MCP server enables Claude to see your project's Kanban board, understand what to work on next, and move cards as tasks are completed.

Quick Start (Recommended)

The easiest way to connect is using the Connect to Claude Code button in the Orchid web UI:

1. Install the MCP Server

   npm install -g orchid-mcp

2. Add to Claude Code

   claude mcp add orchid-mcp -s user -- npx orchid-mcp

   The -s user flag makes this available in all your projects

3. Restart Claude Code (close and reopen)

4. Connect from Orchid

   • Go to orchid-kappa.vercel.app
   • Open your project
   • Click the "Connect to Claude Code" button
   • The API key is automatically configured!

5. Start Working

   "What's next on my Orchid board?"

Alternative: Manual Setup

If you prefer to configure the API key manually:

1. Generate an API Key

1. Log in to Orchid
2. Click your avatar → "API Keys"
3. Click "Generate New Key"
4. Copy the key (you'll only see it once!)

2. Set Environment Variable

Add to your ~/.bashrc or ~/.zshrc:

export ORCHID_API_KEY=orch_your_key_here

Then reload your shell:

source ~/.zshrc  # or source ~/.bashrc

3. Restart Claude Code

After setting the environment variable, restart Claude Code for the changes to take effect.

Install the Orchid Project Agent Skill (Optional)

The package includes the Orchid Project Agent skill, which helps Claude guide you through project planning and generate ORCHID.md files.

To install the skill in your project:

# Create the skills directory if it doesn't exist
mkdir -p .claude/skills

# Copy the skill from the npm package
cp $(npm root -g)/orchid-mcp/skills/orchid-project-agent.md .claude/skills/

Then in Claude Code, say:

Help me plan a new project using the orchid-project-agent skill

Available Tools

Connection & Discovery

Read Operations

Write Operations

Example Workflow

User: "Let's work on my VoiceKeep project"

Claude: [calls connect_project]
"Connected to VoiceKeep! You have:
 - Backlog: 5 cards
 - On Deck: 2 cards
 - In Progress: 1 card
 - Complete: 3 cards

What should I work on?"

User: "What's next?"

Claude: [calls get_next_card]
"The next priority card is 'Add user authentication'.
Want me to start on it?"

User: "Yes"

Claude: [calls start_card]
"Card moved to In Progress. Let me get the details..."

Claude: [calls get_card_details]
"Card: Add user authentication

 Acceptance Criteria:
 - Users can sign in with Google
 - Session persists across refreshes
 - Logout clears session

 Starting implementation..."

[Claude implements each requirement]

Claude: [calls update_acceptance_criteria for each criterion as completed]
"✓ Completed: Users can sign in with Google"
"✓ Completed: Session persists across refreshes"
"✓ Completed: Logout clears session"

Claude: [calls add_comment with completion summary]
"Added completion summary to card."

Claude: "All acceptance criteria complete!

Summary of changes:
- Integrated Google OAuth with Supabase Auth
- Added session persistence with secure cookies
- Implemented logout with session clearing

Please review the work. Ready to mark this card as Complete?"

User: "Looks good!"

Claude: [calls complete_card]
"Card marked complete! Would you like to work on the next card?"

Configuration File

When you use the "Connect to Claude Code" button, your API key and active project are saved to:

~/.orchid/config.json

This persists across Claude Code restarts, so you don't need to reconnect each time.

Troubleshooting

"MCP not found" or commands don't work

# Verify installation
claude mcp list

# Reinstall if needed
claude mcp remove orchid-mcp
claude mcp add orchid-mcp -s user -- npx orchid-mcp

"Invalid API key" error

• Use the Connect button in Orchid to auto-configure
• Or check your environment variable: echo $ORCHID_API_KEY

Need to switch projects?

Just tell Claude: "Connect to [project name]" or use the Connect button in Orchid.

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Watch mode
pnpm dev

License

MIT