Skip to content

MCP_SERVERS.md

Latest commit

 

History

History
266 lines (192 loc) · 9.15 KB

MCP_SERVERS.md

File metadata and controls

266 lines (192 loc) · 9.15 KB

MCP (Model Context Protocol) Servers Configuration

This document describes the MCP servers that can be configured for Claude Desktop and Claude Code.

Overview

The macbook-dev-setup project includes several scripts to manage MCP servers:

  • setup-claude-mcp.sh - Installs and configures MCP servers for Claude Desktop
  • setup-claude-code-mcp.sh - Configures MCP servers for Claude Code CLI
  • fix-mcp-servers.sh - Repairs MCP configuration with dynamic server selection
  • debug-mcp-servers.sh - Tests and debugs MCP server installations

Official Servers

These servers are maintained by the official MCP team:

  1. filesystem - Secure file operations with access controls
  2. memory - In-memory key-value storage for temporary data
  3. git - Tools to read, search, and manipulate Git repositories
  4. fetch - Web content fetching and conversion
  5. sequentialthinking - Dynamic problem-solving through thought sequences

Plugin-Managed Servers

These servers are now managed via Claude Code plugins (installed with /plugin install):

  1. github (github@claude-plugins-official)

    • Native GitHub MCP — richer PR/issue context than gh CLI alone
    • Installed as user-scope plugin

  2. playwright (playwright@claude-plugins-official)

    • Browser automation and web scraping capabilities
    • Previously configured as manual MCP; now managed via plugin

  3. slack (slack@claude-plugins-official)

    • Slack MCP for reading/sending messages from Claude

  4. pr-review-toolkit (pr-review-toolkit@claude-plugins-official)

    • Specialized PR review agents, complements reviewer sub-agent

LSP Plugins (Code Intelligence)

These plugins provide auto-diagnostics after every edit + code navigation (jump-to-def, find refs):

  • typescript-lsp — requires typescript-language-server (brew)
  • swift-lsp — requires sourcekit-lsp (bundled with Xcode)
  • pyright-lsp — requires pyright (brew)
  • kotlin-lsp — requires kotlin-language-server (brew)

Plugin-Managed Servers (Migrated)

These were previously community MCP servers, now managed via plugins:

  • context7 (context7@claude-plugins-official) — library docs lookup via npx @upstash/context7-mcp
  • playwright (playwright@claude-plugins-official) — browser automation (previously listed above)
  • figma (figma@claude-plugins-official) — Figma design data via hosted OAuth (no API key needed)

Community Servers

These servers are still installed from source:

  1. semgrep (https://github.com/semgrep/mcp)

    • Security scanning and code analysis
    • Helps identify vulnerabilities and code patterns

  2. exa (https://github.com/exa-labs/exa-mcp-server)

    • AI-optimized search engine integration
    • Better web search results for AI agents

  3. taskmaster (https://github.com/eyaltoledano/claude-task-master)

    • AI-powered task management and project planning
    • Dual role functionality:
      • As "taskmaster" MCP server: Direct task commands (task-master list, task-master next)
      • As "Product Manager" sub-agent: Product discovery, customer validation, risk assessment
    • Features PRD parsing, task generation, and complexity analysis
    • Optional research capabilities with Perplexity API
    • Naming convention: Use "taskmaster" for MCP operations, "Product Manager" for agent workflows

Pieces MCP

Pieces MCP requires special configuration:

  • Requires PiecesOS running locally
  • Configure manually with SSE endpoint: http://localhost:39300/model_context_protocol/2024-11-05/sse
  • Provides long-term memory and context-aware coding assistance

Troubleshooting

Common Issues

  1. Server not found

    # Check if server is installed
./scripts/debug-mcp-servers.sh

# Reinstall servers
./scripts/setup-claude-mcp.sh

  2. API key not working

    • Ensure API keys are exported in ~/.config/zsh/51-api-keys.zsh
    • Reload shell: source ~/.zshrc
    • Verify key is set: echo $EXA_API_KEY

  3. Claude Desktop not recognizing servers

    • Restart Claude Desktop after configuration
    • Check config file: cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
    • Run fix script: ./scripts/fix-mcp-servers.sh

  4. Claude Code CLI issues

    • List current servers: claude mcp list
    • Remove and re-add: claude mcp remove <server> then re-run setup
    • Check configuration: claude settings show

Installation

Claude Desktop

# Install all MCP servers
./scripts/setup-claude-mcp.sh

# Fix/update configuration
./scripts/fix-mcp-servers.sh

# Exclude servers that need API keys
./scripts/fix-mcp-servers.sh --no-api-keys

# Only install specific servers
./scripts/fix-mcp-servers.sh --servers filesystem,memory,git

# Debug MCP server installations
./scripts/debug-mcp-servers.sh

Claude Code CLI

# Add all servers to user scope (global)
./scripts/setup-claude-code-mcp.sh

# Add to project scope (.mcp.json in current directory)
./scripts/setup-claude-code-mcp.sh --scope project

# Explicitly add to user scope (default)
./scripts/setup-claude-code-mcp.sh --scope user

# Update Exa MCP server specifically
./scripts/update-exa-mcp.sh

Scope Options

  • User Scope (default): Configures MCP servers globally for all Claude Code sessions

    • Configuration stored in ~/.config/claude/claude_code_config.json
    • Available across all projects

  • Project Scope: Configures MCP servers for a specific project

    • Creates .mcp.json in the current directory
    • Takes precedence over user configuration
    • Useful for project-specific servers or API keys

Skip servers requiring API keys

./scripts/setup-claude-code-mcp.sh --no-api-keys

Add specific servers only

./scripts/setup-claude-code-mcp.sh --servers semgrep,exa


## Debugging

```bash
# Test all MCP servers
./scripts/debug-mcp-servers.sh

This will:

  • Check environment variables for API keys
  • Test each server individually
  • Verify Claude Desktop configuration
  • Check Claude Code configuration

Run the setup script to install all servers:

./scripts/setup-claude-mcp.sh

During installation, you'll be prompted for API keys for servers that require them:

  • Exa: Get your API key from https://dashboard.exa.ai/api-keys
  • Taskmaster (optional):
    • Requires ANTHROPIC_API_KEY and OPENAI_API_KEY (usually already configured)
    • Optionally uses PERPLEXITY_API_KEY for research features (https://www.perplexity.ai/settings/api)
    • Works without Perplexity but with limited research capabilities
    • When used as MCP server: Direct task management commands
    • When used as "Product Manager" agent: Comprehensive product discovery workflows

API keys are securely stored in ~/.config/zsh/51-api-keys.zsh and automatically loaded by your shell.

Usage

Once installed, the servers are automatically available in Claude Code. You can:

  1. Check configured servers: claude mcp list
  2. Update servers: ./scripts/setup-claude-mcp.sh --update
  3. Remove servers: ./scripts/setup-claude-mcp.sh --remove

Prerequisites

  • Node.js and npm (for TypeScript servers)
  • Python 3 and uv (for Python servers)
  • Claude Code CLI
  • For specific servers:
    • Exa: Requires API key (will be prompted during setup)
    • Figma: Now a plugin (no API key needed — uses hosted OAuth)
    • Semgrep: May require Semgrep CLI installation
    • Pieces: Requires PiecesOS running locally

Troubleshooting

Connection Issues

To debug MCP connection failures:

  1. Run claude mcp list to see connection status
  2. Use ./scripts/debug-mcp-servers.sh to test individual servers
  3. Check API keys are set: echo $EXA_API_KEY
  4. Restart Claude after configuration changes: osascript -e 'quit app "Claude"' && open -a "Claude"

Common Issues

Exa server fails to connect:

  • Ensure EXA_API_KEY is set in your shell environment
  • Check ~/.config/zsh/51-api-keys.zsh contains the key
  • Reload your shell or run source ~/.zshrc

Note: Figma and Playwright are now managed as plugins, not MCP servers. Use /plugin install figma@claude-plugins-official and /plugin install playwright@claude-plugins-official.

Semgrep server fails:

  • Requires Python and uv package manager
  • Run cd ~/repos/mcp-servers/community/semgrep && uv sync

Configuration gets corrupted:

  • Backup exists at ~/.setup-backups/configs/claude-mcp/
  • Or use ./scripts/fix-mcp-servers.sh to reset

Product Manager (TaskMaster) not showing research options:

  • Check if Perplexity API key is set: echo $PERPLEXITY_API_KEY
  • If not set, research features are disabled but product management still works
  • Add key to ~/.config/zsh/51-api-keys.zsh and restart Claude to enable
  • Product discovery features work via AI simulation even without Perplexity

If a server fails to build or install:

  1. Check that all prerequisites are installed
  2. Ensure you have internet connectivity for cloning repositories
  3. Some servers may have pre-built distributions and don't require building
  4. Check the logs for specific error messages

Directory Structure

~/repos/mcp-servers/
├── official/          # Official MCP servers
├── community/         # Community MCP servers
└── custom/           # Custom/local MCP servers