本地MCP服务器：完整指南
本指南详细介绍了如何构建本地模型上下文协议（MCP）服务器、对其进行配置，并将其连接到如Claude Desktop和VS Code（Copilot）等大型语言模型（LLM）客户端。
______________________________________________________________________
什么是MCP（模型上下文协议）？
MCP基本上是服务器的一种标准；它只是一个遵循特定模板的Web服务器。它提供了一个标准接口，使得大型语言模型（LLMs）能够访问工具和数据。我们基本上允许大型语言模型在它们认为需要时自主进行自定义函数调用和数据检索。
这允许你为大型语言模型（LLM）提供“工具”，比如掷骰子、访问本地文件或调用私有API的能力，以便它能用来回答你的问题。
______________________________________________________________________
工作原理：两部分系统
理解这个设置的关键在于认识到它有两个独立的组成部分： 服务器 和（the） 网关。
- MCP服务器（例如。，
dice-mcp-server)
- 类比：厨师👨🍳 - 这是你构建的Docker镜像。它包含了你实际的代码（例如，一个Python脚本），这些代码知道如何执行任务，比如： roll_dice这是完成工作的“厨房”。
- MCP网关（例如。，
docker/mcp-gateway）
- 类比：经理 👔 - 这是一个官方的Docker镜像，它扮演着“管理者”或“前台”的角色。它是LLM客户端（如Claude/VS Code）唯一交互的对象。它的职责是读取你的配置文件，并指示正确的“厨师”（即你的服务器）执行相应的操作。
你构建了 厨师 并配置 经理。
架构流程
以下是一张图表，展示了用户、客户端、网关和您的服务器之间的交互方式。
graph TB
subgraph user[" "]
A["👤 USER
Ask AI anything"]
end
subgraph client[" "]
B["💻 AI CLIENT
Claude Desktop
VS Code Copilot
Cursor
Any MCP-enabled app"]
end
subgraph gateway[" "]
C["🌉 DOCKER MCP GATEWAY
Smart Orchestrator
📋 Manages multiple servers
🔌 Routes tool requests
⚙️ Handles connections"]
end
subgraph servers[" "]
direction LR
E1["🔧 SERVER 1
Database Tools"]
E2["🔧 SERVER 2
API Integration"]
E3["🔧 SERVER 3
File Processing"]
E4["🔧 SERVER N
Your Custom Logic"]
end
subgraph examples[" "]
direction LR
F["💾 DATABASES
PostgreSQL
MongoDB
Redis
SQLite"]
G["🌐 EXTERNAL APIS
GitHub
Slack
Payment APIs
Weather, Stock"]
H["📁 FILE SYSTEMS
Read/Write files
Process CSVs
Generate PDFs
Image manipulation"]
I["⚡ CUSTOM TOOLS
Business logic
Calculations
Validations
Automation"]
end
A ==>|"① Natural language query"| B
B ==>|"② Discovers available tools
Sends tool request"| C
C ==>|"③ Routes to appropriate server"| E1 & E2 & E3 & E4
E1 -.->|"accesses"| F
E2 -.->|"accesses"| G
E3 -.->|"accesses"| H
E4 -.->|"accesses"| I
E1 & E2 & E3 & E4 ==>|"④ Executes & returns results"| C
C ==>|"⑤ Aggregates responses"| B
B ==>|"⑥ Natural language answer"| A
classDef userStyle fill:#FF6B6B,stroke:#C92A2A,stroke-width:3px,color:#FFF
classDef clientStyle fill:#4ECDC4,stroke:#0B7285,stroke-width:3px,color:#FFF
classDef gatewayStyle fill:#45B7D1,stroke:#1971C2,stroke-width:3px,color:#FFF
classDef serverStyle fill:#A78BFA,stroke:#6D28D9,stroke-width:2px,color:#FFF
classDef exampleStyle fill:#FFA07A,stroke:#E8590C,stroke-width:2px,color:#FFF
class A userStyle
class B clientStyle
class C gatewayStyle
class E1,E2,E3,E4 serverStyle
class F,G,H,I exampleStyle______________________________________________________________________
前提条件检查
- Docker Desktop（中文可译为“Docker 桌面版”） 已安装并运行。
- 一个MCP客户端 （例如，Claude Desktop 或带有 Copilot 的 VS Code）。
- 启用 Docker MCP 工具包：
1. 打开 Docker Desktop。 1. 首选 设置 → 测试版功能。 1. 启用 “Docker MCP Toolkit”翻译为中文是“Docker MCP 工具包”。 1. 点击 应用并重启。
______________________________________________________________________
第一步：构建您的工具服务器（即“大厨”）
首先，你需要构建一个包含你实际工具代码的Docker镜像。
# Clone the example repository
git clone https://github.com/chaitanyakartik/local_MCP_template.git
cd src
# Build the Docker image, this creates a local image named "dice-mcp-server"
docker build -t dice-mcp-server .______________________________________________________________________
步骤2：创建您的配置文件（“菜单”）
这是最关键的部分。你必须在特定文件夹中创建两个文件，以告知“Manager”（网关）关于你的“Chef”（厨师，这里可能指的是某个配置或管理实体）的信息 dice-mcp-server）。
进入你的主文件夹 （例如。， /Users/your-name/ 或者 C:\Users\your-name\）。 找到或创建隐藏的 .docker 文件夹，并在其中创建一个 mcp 文件夹。
完整路径将是：
- macOS：
/Users/your-name/.docker/mcp - Windows：
C:\Users\your-name\.docker\mcp
在这个里面 mcp 文件夹，创建以下内容：
1. 注册表文件（“启用”列表）
这个文件告诉网关 *哪个/那（用于指代或询问特定的事物或情况）* 您的自定义服务器已启动。
- 创建这个文件：
~/.docker/mcp/registry.yaml - 粘贴以下确切内容：
dice:
ref: ""*（注：该 ref: 必须缩进两个空格。)*
2. 目录文件（“菜单”）
此文件描述了您的服务器及其工具。
- 创建这个文件夹：
~/.docker/mcp/catalogs/ - 创建这个文件：
~/.docker/mcp/catalogs/custom.yaml - 粘贴以下确切内容：
version: 2
name: custom
displayName: Custom MCP Servers
registry:
dice:
description: "Dice rolling for tabletop games"
title: "Dice Roller"
type: server
dateAdded: "2025-01-01T00:00:00Z"
image: dice-mcp-server:latest
ref: ""
tools:
- name: flip_coin
- name: roll_dice
- name: roll_custom
- name: roll_stats
- name: roll_advantage
- name: roll_disadvantage
- name: roll_check
- name: roll_initiative
metadata:
category: productivity
tags:
- gaming
- dice
- randomization______________________________________________________________________
步骤3：连接大型语言模型客户端（即“管理器”）
这就是我们告诉您的客户端（Claude 或 VS Code）如何运行“管理器”（网关）的地方。我们将使用一个明确的命令来 *不能失败* 找到你的配置文件。
首先，获取 完整、绝对路径 致你的 mcp 文件夹（例如。， /Users/chaitanyakartik/.docker/mcp 或者 C:\Users\YourUser\.docker\mcp）。
选项A：连接到Claude桌面版
- 打开您的Claude桌面配置文件：
- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - Windows： %APPDATA%\Claude\claude_desktop_config.json
- 粘贴以下JSON。 你必须更换
YOUR_FULL_PATH_HERE根据你实际的路径。
{
"mcpServers": {
"docker-mcp-gateway-explicit": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-v", "/var/run/docker.sock:/var/run/docker.sock",
/*
THIS IS THE CRITICAL LINE.
It maps your local config folder into the container.
*/
"-v", "YOUR_FULL_PATH_HERE:/mcp",
"docker/mcp-gateway",
"--registry=/mcp/registry.yaml",
"--catalog=/mcp/catalogs/docker-mcp.yaml",
"--catalog=/mcp/catalogs/custom.yaml",
"--transport=stdio"
]
}
}
}- Windows 用户： 记得使用双反斜杠（\\) 对于你的路径，例如。， "C:\\Users\\YourUser\\.docker\\mcp:/mcp"。
选项B：连接到VS Code（Copilot）
- 在 VS Code 中，打开命令面板（
Ctrl+Shift+P或者Cmd+Shift+P）。
- 运行该命令
MCP: Open User Configuration。
- 这将打开您的
mcp.json文件。
- 粘贴以下JSON。 你必须更换
YOUR_FULL_PATH_HERE根据你的实际路径。
{
"servers": {
"docker-mcp-gateway-explicit": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-v",
"/var/run/docker.sock:/var/run/docker.sock",
/*
THIS IS THE CRITICAL LINE.
It maps your local config folder into the container.
*/
"-v",
"YOUR_FULL_PATH_HERE:/mcp",
"docker/mcp-gateway",
"--registry=/mcp/registry.yaml",
"--catalog=/mcp/catalogs/docker-mcp.yaml",
"--catalog=/mcp/catalogs/custom.yaml",
"--transport=stdio"
],
"type": "stdio"
}
},
"inputs": []
}- Windows 用户： 记得使用双反斜杠（\\) 为你指定的路径，例如。， "C:\\Users\\YourUser\\.docker\\mcp:/mcp"。
______________________________________________________________________
步骤4：进行测试！
- 彻底退出并重新启动 Claude Desktop 或 VS Code。
- 开启一个新聊天。
- 点击 工具 图标（或按下
Cmd/Ctrl+I)。 - 你应该能看到你的网关列在其中：
docker-mcp-gateway-explicit。 - 在其下方，你应该能看到你所有的骰子工具：
roll_dice，flip_coin等。 - 试试看！“掷2个6面骰子加3点伤害”
如果一切正常，您就已成功构建并配置了一个本地MCP服务器。
______________________________________________________________________
致谢
本指南及 dice-mcp-server 这些示例在很大程度上依赖于NetworkChuck提供的优秀教程和代码。
- GitHub 仓库：
- 原始YouTube教程： 你现在需要学习MCP（模型上下文协议）