Setting up MCP Servers in Claude Code

What is Claude Code?

Claude Code is Anthropic's official CLI tool for AI-assisted coding. It brings Claude's capabilities directly to your terminal, enabling code generation, refactoring, debugging, and more through natural language commands.

What is MCP?

MCP (Model Context Protocol) follows a client-server architecture where:

• MCP clients (like Claude Code) connect to MCP servers and request actions on behalf of the AI model
• MCP servers provide tools that expose specific functionalities through a well-defined interface
• The protocol defines the message format for communication between clients and servers

Prerequisites

• Claude Code CLI installed (npm install -g @anthropic-ai/claude-code)
• Node.js 18+ or Bun
• Docker (optional, for containerized MCP servers)
• API key for any MCP servers that require authentication

Installing Claude Code

If you haven't installed Claude Code yet:

# Using npm
npm install -g @anthropic-ai/claude-code

# Using bun
bun install -g @anthropic-ai/claude-code

# Verify installation
claude --version

Configuring MCP Servers

Claude Code uses a JSON configuration file to define MCP servers. There are two configuration locations:

1. Project-Level Configuration (Recommended)

Create a .claude/mcp.json file in your project root:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-filesystem", "/path/to/allowed/dir"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

2. Global Configuration

For servers available across all projects, create ~/.claude/mcp.json:

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    }
  }
}

Popular MCP Servers for Claude Code

Filesystem & Storage

• @anthropic-ai/mcp-server-filesystem - Read/write files in allowed directories
• @anthropic-ai/mcp-server-google-drive - Access Google Drive documents

Development Tools

• @anthropic-ai/mcp-server-github - Create issues, PRs, and manage repositories
• @anthropic-ai/mcp-server-git - Git operations (status, diff, commit, push)
• @anthropic-ai/mcp-server-postgres - PostgreSQL database queries

Search & Research

• @anthropic-ai/mcp-server-brave-search - Web search via Brave Search API
• @anthropic-ai/mcp-server-fetch - Fetch and process web content

Productivity

• @anthropic-ai/mcp-server-slack - Read/send Slack messages
• @anthropic-ai/mcp-server-notion - Create/update Notion pages

Starting Claude Code with MCP

Once configured, start Claude Code in your project:

cd /path/to/your/project
claude

Claude Code will automatically detect and load MCP servers from .claude/mcp.json.

Verifying MCP Servers

When Claude Code starts, you'll see a list of connected MCP servers:

✓ Connected MCP servers:
  - filesystem (read/write files)
  - github (repository management)
  - brave-search (web search)

Using MCP Tools in Claude Code

Once connected, you can use MCP tools naturally in your conversations:

Example 1: File Operations

Read the contents of src/index.ts and suggest improvements

Claude Code will use the filesystem MCP server to read the file and provide suggestions.

Example 2: GitHub Integration

Create a new issue titled "Add unit tests" with a description of what tests we need

Claude Code will use the GitHub MCP server to create the issue.

Example 3: Web Search

Search for the latest Next.js 15 documentation on server components

Claude Code will use the Brave Search MCP server to find relevant information.

Environment Variables

Many MCP servers require API keys. Set them in your shell profile or use a .env file:

# ~/.bashrc or ~/.zshrc
export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
export BRAVE_API_KEY="BSAxxxxxxxxxxxxxx"
export DATABASE_URL="postgresql://user:pass@localhost:5432/db"

Or create a .env file in your project root and load it before starting Claude Code:

source .env
claude

Advanced Configuration

Custom Server Paths

If you have a custom MCP server:

{
  "mcpServers": {
    "my-custom-server": {
      "command": "node",
      "args": ["/path/to/my-mcp-server/index.js"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      }
    }
  }
}

Docker-Based Servers

Run MCP servers in Docker containers:

{
  "mcpServers": {
    "postgres": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "DATABASE_URL", "mcp/postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Server Arguments

Pass additional arguments to MCP servers:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic-ai/mcp-server-filesystem",
        "--allowed-directories",
        "/home/user/projects,/home/user/docs"
      ]
    }
  }
}

Security Considerations

⚠️ Caution: MCP servers can run arbitrary code on your machine. Only add servers from trusted sources, and always review the server configuration before starting it.

🔒 Important: Never hardcode sensitive information like API keys directly in configuration files. Use environment variables or input variables instead.

📁 Filesystem Access: Be specific about which directories MCP servers can access. Avoid granting access to your entire home directory.

Troubleshooting

Server Not Connecting

1. Check the server command and arguments are correct
2. Verify required environment variables are set
3. Ensure the server package is installed (try npx with -y flag)
4. Check Claude Code logs for error messages

Tool Not Available

1. Verify the MCP server is running (claude --debug for verbose output)
2. Check the server's tool list matches what you're trying to use
3. Restart Claude Code after configuration changes

Permission Errors

1. Ensure the MCP server has access to required directories
2. Check file permissions on configuration files
3. Verify API keys have the necessary scopes

Further Resources

• Claude Code Documentation
• MCP Specification
• Official MCP Servers Repository
• Awesome MCP Servers