merlin-mcp

MCP server that gives Claude Code instant access to your codebase context via merlin.build

What This Does

Once installed, Claude Code automatically has deep understanding of any repository you've analyzed on merlin.build:

• No more re-explaining your codebase every session
• No more duplicating code that already exists
• No more guessing at patterns and conventions
• Instant context for any task you're working on

Quick Start

1. Analyze Your Repository

Visit merlin.build and analyze your repository. This takes ~10 minutes and creates comprehensive documentation.

2. Get Your API Key

Go to merlin.build/settings and generate an API key.

3. Configure Claude Code

Option A: Interactive Setup (Recommended)

# Shows logo, validates key, guides you through setup
MERLIN_API_KEY=mrln_xxxxx npx merlin-mcp --setup

Option B: Quick CLI Install

# Add MCP server
claude mcp add merlin npx merlin-mcp@latest -e MERLIN_API_KEY=mrln_xxxxx --scope user

# Verify installation (shows logo, validates key)
npx merlin-mcp --test

Option C: Manual Config

Add to your Claude Code config (~/.claude/config.json):

{
  "mcpServers": {
    "merlin": {
      "command": "npx",
      "args": ["merlin-mcp@latest"],
      "env": {
        "MERLIN_API_KEY": "your-api-key-here"
      }
    }
  }
}

Upgrading from ccwiki/briefed? The old MCP is automatically cleaned up when you start Merlin.

4. Use It

Just start working. Claude Code now automatically has context:

> "Add a new API endpoint for user settings"

Claude knows:
- Where your existing endpoints are
- What patterns they follow
- What middleware to use
- What utilities exist to reuse
- What conventions to follow

Available Tools

Once connected, Claude Code has access to these tools:

| Tool | Description | |------|-------------| | merlin_get_context | Get relevant context for a task (patterns, files, conventions) | | merlin_find_files | Find files by purpose or layer | | merlin_get_conventions | Get coding conventions and anti-patterns | | merlin_quickstart | Get a 60-second codebase overview | | merlin_search | Search documentation for specific topics | | merlin_list_repos | List your analyzed repositories |

How It Works

1. Auto-detection: The MCP server detects which git repository you're in
2. Lookup: It finds the matching analyzed repo on merlin.build
3. Context: It provides relevant context to Claude Code
4. Caching: Responses are cached for fast repeat access

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | MERLIN_API_KEY | Your Merlin API key | Required | | MERLIN_API_URL | API base URL | https://auth.merlin.build |

CLI Commands

# Interactive setup wizard (recommended for first-time setup)
MERLIN_API_KEY=xxx npx merlin-mcp --setup

# Validate setup - shows logo, checks API key, lists repos
npx merlin-mcp --test

# Show help
npx merlin-mcp --help

# Show version
npx merlin-mcp --version

# Run server directly (for testing)
MERLIN_API_KEY=xxx npx merlin-mcp

Troubleshooting

"Could not find repository"

This means either:

1. You're not in a git repository
2. The repository hasn't been analyzed on merlin.build
3. The git remote URL doesn't match what's on merlin

Solution: Make sure the repo is analyzed at merlin.build and you're in the repo directory.

"API request failed: 401"

Your API key is invalid or expired.

Solution: Generate a new API key at merlin.build/settings.

Server not starting

Check that Node.js 18+ is installed:

node --version  # Should be 18.x or higher

Old "briefed" MCP still showing

If you still see briefed in claude mcp list:

# Remove it manually
claude mcp remove briefed --scope user

# Merlin should be the only one
claude mcp list

Note: Merlin automatically cleans up old briefed config when it starts, but the Claude CLI registry needs manual removal.

Development

# Install dependencies
npm install

# Build
npm run build

# Run in development
npm run dev

# Type check
npm run typecheck

License

MIT

Links

• merlin.build - Analyze your repositories
• Documentation - Full documentation
• GitHub - Source code