Claude Code MCP Servers - Setup, .mcp.json and Top Tools

Claude Code MCP servers are lightweight local processes that extend Claude Code beyond file reading and writing by connecting external tools through the Model Context Protocol. They enable querying databases, searching the web, managing GitHub issues, and interacting with APIs while keeping data private through bidirectional communication between Claude Code and each tool.

This guide covers .mcp.json configuration, the best servers worth installing, real workflow examples, and troubleshooting. Our analysis draws on Anthropic’s official Claude Code and Model Context Protocol documentation rather than sponsored placement. AI Productivity may earn a commission from links on this page; our recommendations are editorially independent.

What Are MCP Servers?

An MCP server is a lightweight local process that exposes external tools and data sources to Claude Code through a single open protocol. The Model Context Protocol (MCP) is an open standard created by Anthropic - the company behind Claude - which released it in November 2024, with the full specification published on the official Model Context Protocol documentation site. According to Anthropic, the company that created the protocol, “MCP is an open protocol that standardizes how applications provide context to LLMs,” a universal adapter that replaces per-service custom integrations. The official MCP servers repository on GitHub lists the reference servers covered in this guide alongside dozens of community-built integrations.

Each server exposes callable tools (such as query_database or create_issue), provides resources like file contents and database schemas, and runs locally to keep data private. The key distinction from traditional API integrations is that MCP servers are bidirectional - Claude Code discovers tools, understands their parameters, and decides when to use them.

Why MCP Matters for Claude Code

Without MCP servers, Claude Code is limited to file operations and terminal commands. That misses live SQL queries, web search, browser automation with Puppeteer, and third-party APIs such as GitHub issues. MCP servers fill these gaps - once configured, Claude Code treats them as native capabilities.

How to Set Up MCP Servers in Claude Code

Claude Code MCP server setup requires a .mcp.json config file in the project root with a server entry containing command, args, and env, followed by a restart - or run claude mcp add to write the entry automatically. This is the canonical Claude Code mcp config file format documented by Anthropic.

Step 1: Create the Configuration File

Create .mcp.json in the project root with an mcpServers object. Each server entry has three fields:

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"],
      "env": {}
    }
  }
}

Step 2: Use the Claude Code CLI

The fastest way to add a server is the CLI - claude mcp add server-name -- npx -y package-name writes the entry to .mcp.json automatically, and claude mcp list shows all configured servers.

Step 3: Configure Scope (Project vs Global)

Claude Code supports two scopes. Project scope (the default) uses .mcp.json in the project root; user scope uses ~/.claude/.mcp.json and makes servers available across all projects (append --scope user to claude mcp add). Project scope is recommended - it keeps configurations portable with the codebase.

Step 4: Verify the Connection

After adding a server, restart Claude Code and look for the server name in the startup tool list. If a server fails to start, Claude Code logs the error - common causes are missing dependencies, incorrect paths, or invalid API keys.

Understanding .mcp.json Structure

Multiple servers nest inside one mcpServers object, each as a named key. A few notes:

• Server names must be unique - they become the prefix for tool names (e.g., filesystem__read_file).
• Environment variables in env are passed only to that server process and do not leak.
• Credentials should not be committed - add .mcp.json to .gitignore if it holds API keys.

Best Claude Code MCP Servers

The most useful Claude Code MCP servers for day-to-day development are the filesystem, GitHub, PostgreSQL, Brave Search, Puppeteer, SQLite, Memory, and Fetch servers - all free, open-source, and installable with one claude mcp add command. The table below compares the eight official servers covered in this guide. See our AI tools for developers roundup and best AI code editors 2026 comparison for wider context.

1. Filesystem Server

What it does: Gives Claude Code controlled read and write access to directories outside the current project.

Install: claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/directory

Tools provided: read_file, write_file, list_directory, search_files, get_file_info, create_directory, move_file

2. GitHub Server

What it does: Full GitHub integration - create issues, manage pull requests and branches, search repositories, and read remote files.

Install: claude mcp add github -- npx -y @modelcontextprotocol/server-github

Tools provided: create_issue, list_issues, create_pull_request, get_pull_request, search_repositories, get_file_contents, create_branch, push_files

Token setup: Generate a GitHub personal access token with repo, issues, and pull_requests scopes.

3. PostgreSQL Server

What it does: Connects Claude Code to a PostgreSQL database for read-only queries, discovering schemas automatically and executing SQL from natural-language questions.

Install: claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres postgresql://user:password@localhost:5432/dbname

Tools provided: query (read-only SQL execution). The PostgreSQL psql documentation covers the query interface. Always use a read-only database user for MCP connections.

4. Brave Search Server

What it does: Web search through the Brave Search API - look up documentation and error solutions without switching to a browser.

Install: claude mcp add brave-search -- npx -y @modelcontextprotocol/server-brave-search

Tools provided: brave_web_search, brave_local_search. Sign up at the Brave Search API portal - the free tier includes 2,000 queries per month.

5. Puppeteer Server

What it does: Browser automation and screenshots - navigate pages, fill forms, click buttons, and extract content from rendered web pages.

Install: claude mcp add puppeteer -- npx -y @modelcontextprotocol/server-puppeteer

Tools provided: puppeteer_navigate, puppeteer_screenshot, puppeteer_click, puppeteer_fill, puppeteer_evaluate

6. SQLite Server

What it does: Similar to PostgreSQL but for SQLite databases - ideal for local development, mobile app backends, or embedded analytics.

Install: claude mcp add sqlite -- npx -y @modelcontextprotocol/server-sqlite --db-path /path/to/database.db

Tools provided: read_query, write_query, create_table, list_tables, describe_table, append_insight

7. Memory Server

What it does: Provides persistent key-value storage that survives between Claude Code sessions - useful for project context or architectural decisions.

Install: claude mcp add memory -- npx -y @modelcontextprotocol/server-memory

Tools provided: create_entities, create_relations, search_nodes, open_nodes, delete_entities

8. Fetch Server

What it does: Makes HTTP requests and converts web pages to Markdown - useful for reading documentation or API specs without leaving Claude Code.

Install: claude mcp add fetch -- npx -y @modelcontextprotocol/server-fetch

Tools provided: fetch (GET/POST with automatic HTML-to-Markdown conversion). A typical use is reading the Stripe payment-intents documentation before implementing a handler.

Can Claude Code Use Custom MCP Servers?

Yes - Claude Code works with any process that speaks the MCP protocol, so a custom server is one of the most powerful ways to extend it for a specific workflow.

Building a Custom Server with Python

The official MCP Python SDK (pip install mcp) provides the framework. Here is a minimal custom tool:

from mcp.server import Server
from mcp.types import Tool, TextContent

server = Server("my-custom-server")

@server.list_tools()
async def list_tools():
    return [Tool(name="lookup_customer", description="Look up a customer by email",
                 inputSchema={"type": "object", "properties": {"email": {"type": "string"}}})]

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    customer = await fetch_customer(arguments["email"])  # your logic here
    return [TextContent(type="text", text=str(customer))]

The server registers tools through a list_tools handler and runs logic in call_tool. Register it in .mcp.json with "command": "python" and the script path.

Building a Custom Server with TypeScript

For TypeScript projects, the official TypeScript SDK follows the same pattern - install @modelcontextprotocol/sdk, create a Server, register tools/list and tools/call handlers, and connect a StdioServerTransport. Register the script with a node command.

Custom Server Ideas for Development Teams

Real Workflow Examples

MCP servers let Claude Code chain multiple tools into one autonomous workflow without manual hand-offs.

Full-stack bug investigation: Claude Code reads a GitHub issue, queries Postgres for recent orders, reads the pricing logic from the filesystem server, checks library behavior via Brave Search, then writes the fix and opens a PR. Our best AI coding assistants 2026 roundup compares orchestrated workflows.

Documentation-driven development: The Fetch server reads the OpenAPI spec, Claude Code generates the handler, and Puppeteer validates the response on localhost.

Codebase migration: Filesystem reads patterns from a reference project, Claude Code applies the migration file by file, and the Memory server stores decisions along the way.

Claude Code vs Cursor MCP: What Is the Difference?

Claude Code and Cursor both support the same MCP protocol, but Claude Code manages servers through a CLI and a project-root .mcp.json file while Cursor uses a settings UI and .cursor/mcp.json. See our Cursor vs Windsurf breakdown for a head-to-head.

Configuration

When to Choose Each

Claude Code fits terminal-centric workflows, agentic execution (running tests, managing git), and teams that prefer version-controlled CLI configuration. Cursor fits when visual code editing with inline AI suggestions is the priority. Windsurf also supports MCP - the protocol is identical across all three.

Portability Across Tools

Since MCP is an open standard, the same server configuration works across Claude Code, Cursor, and Windsurf - only the config file location differs (.mcp.json, .cursor/mcp.json, .windsurf/mcp.json). A common pattern is to keep a canonical mcp-servers.json in the project root and symlink it. Our GitHub Copilot vs Cursor comparison covers editor portability.

Troubleshooting Claude Code MCP Servers

Most Claude Code MCP server failures trace to four causes - a missing runtime, a wrong package name, an unset environment variable, or a stale config needing a restart. If one server misbehaves, run claude mcp remove server-name, then re-add it cleanly.

Server Fails to Start

When Claude Code reports “failed to connect to server”, the cause is usually a missing runtime (node, npx, python, or uvx not on PATH), a package not found error (run the install command manually to verify the name), or permission denied (check file permissions on the target directory or port).

Tools Not Appearing

If a server starts but no tools show up, restart Claude Code after modifying .mcp.json, check that the server name has no spaces, and verify the server implements the tools/list handler.

Environment Variables Not Loading

If a server starts but API calls fail with authentication errors, double-check the env block - variable names are case-sensitive, and API keys must have no trailing whitespace.

Slow Server Responses

If Claude Code hangs waiting for MCP results, add connection pooling for database servers, pre-download Chromium for Puppeteer (npx puppeteer browsers install chrome), and break long operations into smaller steps.

Windows-Specific Issues

On Windows, use double backslashes or forward slashes in JSON paths, and supply the full path to npx or the Python executable if either is not on PATH.

Debugging Server Communication

Run claude --mcp-debug to enable verbose logging - it prints every message exchanged between Claude Code and MCP servers.

Advanced Configuration Tips

Advanced Claude Code MCP setups rely on three practices - swapping context-specific .mcp.json files, keeping credentials out of version control, and standardizing a shared template.

Conditional Server Loading

Not every server needs to run for every task. Keep separate .mcp.json files per context (such as .mcp-database.json and .mcp-web.json) and copy the right one into place, or toggle servers with claude mcp remove and claude mcp add.

Security Best Practices

1. Never commit credentials - Add .mcp.json to .gitignore and commit a .mcp.json.example with placeholder values instead.
2. Use read-only database users - Create a dedicated database user with SELECT-only permissions even though the Postgres server enforces read-only mode.
3. Limit filesystem access - Grant the filesystem server only the directories Claude Code actually needs.
4. Rotate API keys regularly - MCP API keys should follow the same rotation policy as any other credential.

Team Configuration Patterns

For teams, commit a shared .mcp.json template that references credentials through environment-variable placeholders (such as "${GITHUB_TOKEN}"). Each developer sets the actual values locally.

The Bottom Line

Claude Code MCP servers turn a terminal-based coding assistant into a fully connected development environment in minutes - create a .mcp.json file, add server entries, and restart Claude Code. Start with the filesystem and GitHub servers, add Brave Search for web lookups, and connect database servers for data-heavy features. For teams already using Claude Code, MCP servers are the highest-impact upgrade available in 2026.

FAQ

What are Claude Code MCP servers?

Claude Code MCP servers are lightweight local processes that extend Claude Code beyond reading and writing files - they expose callable tools, provide resources like file contents and database schemas, and run locally to keep data private.

How does the Model Context Protocol work with Claude Code?

The Model Context Protocol is an open standard created by Anthropic that defines how AI assistants communicate with external tools. MCP servers are bidirectional, so Claude Code discovers available tools, understands their parameters, and decides when to use them.

Why do MCP servers matter for Claude Code workflows?

Without MCP servers, Claude Code is limited to file operations and terminal commands, missing database queries, web search, browser automation, and third-party APIs. MCP servers fill those gaps and let Claude Code treat external services as native capabilities.

How do you add an MCP server in Claude Code?

To add MCP server entries in Claude Code, run claude mcp add server-name -- npx -y package-name, which writes the entry to the project’s .mcp.json config file automatically. To add MCP globally so a server is available across every project, append the --scope user flag, which writes to ~/.claude/.mcp.json instead of the project root. To remove MCP server entries, run claude mcp remove server-name.

Are Claude code MCP servers free?

Yes - every reference Claude code MCP server is free and open-source under MIT license. The eight servers covered here ship from the official Claude code MCP servers GitHub repository at modelcontextprotocol/servers, and the only paid component is third-party API usage (for example, Brave Search beyond its 2,000-query free tier).

Related Reading

These guides go deeper on Claude Code, competing editors, and choosing the right model.

• Claude Code Review: Full Tool Overview - Features, pricing, and ratings
• Claude Review - Anthropic’s Claude AI assistant reviewed
• Cursor Review - AI-native code editor with Composer
• Windsurf Review - AI code editor with MCP support
• Claude Code Pricing in 2026 - Plans and costs
• Which Claude Model for Coding - Picking the right model
• Cursor vs Windsurf - Head-to-head editor comparison

External Resources

These primary sources cover the Model Context Protocol specification and Claude Code’s official documentation.

• Model Context Protocol Official Documentation - Protocol specification and server registry
• Claude Code Documentation - Official setup and configuration reference
• MCP Servers GitHub Repository - Source code for official MCP servers