CoreMate Vibe Code 教程 · English

Claude Code MCP Complete Guide

Claude Code is Anthropic's official AI command-line tool, while MCP Model Context Protocol is the protocol that allows Claude Code to connect to external tools and services.

Content adapted from Datawhale Easy-Vibe, licensed under CC BY-NC-SA 4.0.

What is Claude Code MCP?

Claude Code is Anthropic's official AI command-line tool, while MCP (Model Context Protocol) is the protocol that allows Claude Code to connect to external tools and services.

Put simply, MCP turns Claude Code from an AI assistant that can only read and write local files into a super assistant that can access GitHub, databases, APIs, and cloud services.

Why use MCP in Claude Code?

Claude Code without MCP

What you can do:
✓ Read local files
✓ Edit code
✓ Run commands
✓ Use Bash tools

What you cannot do:
✗ View your GitHub Issues
✗ Access a cloud database
✗ Call external APIs
✗ Get real-time weather

Claude Code with MCP

What you can do:
✓ All original functions
✓ View / create GitHub Issues and PRs
✓ Query SQLite and PostgreSQL databases
✓ Access external services such as Notion and Slack
✓ Get real-time weather and map data
✓ Browser automation
✓ ...and more

Quick Start

Step 1: Understand where the config files live

Claude Code's MCP configuration files are located at:

Level Config file path Scope
User level ~/.claude.json All projects
Project level .claude/mcp.json Current project

It is recommended to use project-level config first, so different projects can use different MCP services.

Step 2: Add MCP servers with natural language

In Claude Code, you do not need to manually edit configuration files or memorize commands. You can describe what you want in natural language:

You: Help me add a GitHub MCP server. My token is ghp_xxx

Claude: I'll help you configure the GitHub MCP server...

[Automatically updates .claude/mcp.json]

You: Add a SQLite database server. The database file is at ./data/app.db

Claude: Okay, I'll configure the SQLite MCP server...

You: Add an HTTP-type MCP server with the address https://api.example.com/mcp

Claude: I'll add that remote MCP server...

Step 3: Verify the configuration

Ask Claude Code directly:

You: What MCP servers are available now?

Claude: Currently configured MCP servers:
• github - GitHub integration
• sqlite - SQLite database
• filesystem - Filesystem access

Or use the diagnostic command:

/doctor

Step 4: Start using it

Once configuration succeeds, you can call MCP functions directly with natural language:

You: Help me create an Issue on GitHub

Claude: I can help you create a GitHub Issue. Please tell me:
- the repository address, for example owner/repo
- the Issue title
- the Issue description

Natural-language management in Claude Code

View and manage MCP servers

You can interact with Claude Code entirely in natural language:

You: List all configured MCP servers

You: Check the connection status of the MCP servers

You: Delete the MCP server named notion

You: Update the token for the github server

Diagnose problems

When you run into problems:

You: Check what's wrong with the MCP connection

Claude: [will automatically run diagnostics, analyze configuration files, and check server status]

Configuration methods in detail

User-level config, global

Edit ~/.claude.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
      }
    }
  }
}

Project-level config, recommended

Edit .claude/mcp.json in the project root:

{
  "mcpServers": {
    "project-db": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "./data/app.db"]
    }
  }
}

Advantages of project-level config:

  • Team members can share the config by committing it to Git
  • Different projects can use different MCP services
  • Configuration is more flexible and does not pollute global settings

Transport modes

Claude Code supports three transport modes:

STDIO, local process

{
  "mcpServers": {
    "local-tool": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
    }
  }
}

HTTP, remote service

{
  "mcpServers": {
    "remote-api": {
      "url": "https://api.example.com/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

SSE, server-sent events

{
  "mcpServers": {
    "streaming": {
      "url": "https://api.example.com/sse",
      "transport": "sse"
    }
  }
}

Practical examples

Example 1: GitHub workflow automation

You: Help me push the current changes to GitHub, then create a PR titled "Add new feature"

Claude:
1. Check current git status...
2. Create a new branch feature/new-feature...
3. Commit changes...
4. Push to remote...
5. Call github_create_pull_request to create the PR...
6. PR created: https://github.com/owner/repo/pull/123

Example 2: Database query

You: Query the 10 most recently registered users in the database

Claude:
1. Connect to the SQLite database...
2. Execute query: SELECT * FROM users ORDER BY created_at DESC LIMIT 10
3. Return results:
   - Zhang San (zhang@example.com) - 2025-02-28
   - Li Si (li@example.com) - 2025-02-27
   ...

Example 3: Webpage screenshot analysis

You: Open https://example.com, take a screenshot, and analyze the page design

Claude:
1. Launch browser...
2. Navigate to https://example.com...
3. Capture screenshot...
4. [Returns screenshot]
5. Page design analysis:
   - The layout uses a centered design with a max width of 1200px
   - The main color is blue (#3b82f6)
   - The navigation bar is fixed to the top
   ...

Example 4: Integration with Notion

You: Save the notes I just wrote to Notion

Claude:
1. Use the Notion MCP server...
2. Create a new page...
3. Saved: https://notion.so/page/xxx

Debugging tips

Diagnose with natural language

When something goes wrong, just tell Claude Code directly:

You: My MCP server cannot connect. Please check it for me

You: The GitHub MCP tool call failed. What is the reason?

You: Why does the sqlite server always show "connecting"?

Claude Code will automatically:

  1. Check the configuration file format
  2. Validate environment variables
  3. Test the server connection
  4. Provide concrete fix suggestions

Common problem troubleshooting

Problem Possible cause Solution
Server not connected Config file format error Check JSON syntax
Tool cannot be called Insufficient permissions Check environment variables
Connection timeout Network problem Check URL or network
Process crashes Bug in server code Check server logs

Manual diagnostic command

/doctor

Example output:

System Diagnostic Report:
===============

Claude Code: v2.5.0 ✓
Node.js: v20.0.0 ✓

MCP server status:
• github: ✓ Connected (12 tools)
• sqlite: ✗ Connection failed - Database file not found
• puppeteer: ✓ Connected (8 tools)

Suggestions:
1. Check whether the sqlite database path is correct
2. Make sure the .claude/mcp.json format is correct

Best practices

1. Prefer project-level configuration

Why recommend project-level configuration?

Different projects often need different MCP services. For example, a frontend project may need browser testing tools, while a backend project may need database connections. With project-level configuration, each project can have its own dedicated set of MCP servers, avoiding the chaos of one large global config.

More importantly, project-level config can be committed to Git. After team members clone the project, they can directly use the same MCP services without reconfiguring everything.

Project A, frontend project -> .claude/mcp.json contains browser testing MCP
Project B, backend project -> .claude/mcp.json contains database MCP

2. Store sensitive information in environment variables

Never hard-code secrets in the configuration file.

Configuration files may be accidentally committed to Git and leak keys. The correct approach is to store sensitive values in environment variables and only reference the variable names from the config file. That way, even if the config file becomes public, the real secrets are still hidden.

{
  "env": {
    "GITHUB_TOKEN": "$GITHUB_TOKEN",
    "GITHUB_TOKEN": "ghp_abc123"
  }
}

The first form is good because it reads from the environment variable. The second form is bad because it hard-codes a secret directly.

3. Pin versions

Why do you need to pin versions?

By default, npx -y will always use the latest version of an MCP server. This can cause problems: a new version may introduce breaking changes, or a package may suddenly be removed or renamed.

By appending @version to the package name, you ensure that a validated version is always used, reducing surprises caused by automatic upgrades.

{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github@1.2.3"]
}

4. Document your MCP configuration

Help teammates understand the MCP setup quickly

When a project includes multiple MCP servers, new team members may not understand what each server is for or what configuration it requires. Creating a README.md under the .claude/ directory that explains each server's purpose, required config, and how to obtain credentials can significantly reduce communication cost.

Create .claude/README.md in your project:

# MCP Configuration Notes

MCP servers used in this project:

## github
Used for GitHub automation. Requires GITHUB_TOKEN.

## sqlite
Connects to ./data/app.db for querying and modifying data.

## puppeteer
Used for E2E testing.

Claude Code vs Claude Desktop

Feature Claude Code Claude Desktop
Config file ~/.claude.json or .claude/mcp.json claude_desktop_config.json
Project-level config ✓ Supported ✗ Not supported
Natural-language management ✓ Supported ✗ Manual editing required
Diagnostics ✓ /doctor ✗ None
Hot reload ✓ Automatic ✗ Requires app restart
Use cases Development workflow, CI/CD Daily use, office tasks

Common MCP servers

💡 For the complete MCP server list, please refer to the appendix: MCP Server Directory

GitHub server

Function: Issues, PRs, repository management

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
      }
    }
  }
}

Get a token from: https://github.com/settings/tokens

SQLite server

Function: Query and manage SQLite databases

{
  "mcpServers": {
    "sqlite": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "./data/database.db"]
    }
  }
}

Filesystem server

Function: Access files inside a specified directory

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]
    }
  }
}

Puppeteer browser automation

Function: Browser control, screenshots, automated testing

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

Brave search server

Function: Web search

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your-brave-api-key"
      }
    }
  }
}

Reference resources

Official documentation

Official servers

Tutorial articles

Configuration guides

Development tutorials

MCP server resources

Map and weather services

Community resources

Real-world application cases

内容已部署为站内静态教程页面，图片与链接均使用本站地址。