使用说明

mcp服务器示例

对初学者友好，可扩展 模型上下文协议（MCP） 使用Node.js构建的服务器。克隆它，运行它，并将其用作您自己的MCP集成的基础。

什么是MCP？

这模型上下文协议（MCP）是Anthropic的一个开放标准，允许像Claude这样的人工智能助手以安全、结构化的方式调用外部工具和服务。

把它想象成人工智能的插件系统：

You (user) ──► Claude ──► MCP Server ──► Your tools / APIs / data

这个项目是一个MCP 服务器 --它公开了任何MCP兼容客户端（Claude Desktop、MCP检查器或自定义客户端）都可以调用的工具。

包含的工具

工具	输入	描述
`get_time`	（无）	返回当前服务器时间
`get_weather`	`city` （string）	返回一个城市的模拟天气
`read_file`	`path` （string）	读取文件（沙盒到项目根目录）
`system_info`	（无）	返回平台、CPU、内存和正常运行时间

先决条件

Node.js v18或更高版本
npm（附带Node.js）

验证您的设置：

node --version   # should print v18.x.x or higher
npm --version

快速开始

1.克隆存储库

git clone https://github.com/YOUR_USERNAME/sample-mcp-server.git
cd sample-mcp-server

2.安装依赖项

npm install

3.运行演示客户端

包括 client.js 连接到服务器，列出所有工具，并调用每个工具，这样您就可以立即看到输出——不需要外部客户端。

node client.js

预期产量：

Starting MCP client…
Connected to MCP server.

────────────────────────────────────────────────────────────
  Available tools (4)
────────────────────────────────────────────────────────────
• get_time — Returns the current server date and time in ISO 8601 format.
• get_weather — Returns the current weather conditions for a given city.
• read_file — Reads the contents of a file at the given path. ...
• system_info — Returns information about the host system: ...

────────────────────────────────────────────────────────────
  get_time result
────────────────────────────────────────────────────────────
Current server time: 2026-01-01T10:00:00.000Z

────────────────────────────────────────────────────────────
  get_weather result (city: Amsterdam)
────────────────────────────────────────────────────────────
Weather in Amsterdam is sunny, 18°C

... and so on

连接到克劳德桌面

要将此服务器与Claude Desktop一起使用，请执行以下操作：

1.查找您的Claude Desktop配置文件

操作系统	路径
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
窗户	`%APPDATA%\Claude\claude_desktop_config.json`

2.将此服务器添加到配置中

{
  "mcpServers": {
    "sample-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/sample-mcp-server/server.js"]
    }
  }
}

重要提示： args 必须指向 server.js --不仅仅是文件夹。例如，如果您克隆到主目录：
"args": ["/Users/your-username/sample-mcp-server/server.js"]

3.重新启动克劳德桌面

工具将自动显示。你现在可以问克劳德这样的问题：

“服务器上几点了？”
“东京的天气怎么样？”
“使用read_file工具向我显示package.json”
“显示系统信息。”

提示： 对于 read_file，用短语表达请求，以便克劳德知道使用该工具——例如。 “使用read_file读取…” 或 *“在…上调用read_file工具”*仅说“读取文件X”可能会导致Claude要求您上传文件。

使用MCP检查器（可选）

这 MCP检查员是一个基于浏览器的官方用户界面，用于测试MCP服务器。

npx @modelcontextprotocol/inspector node server.js

然后打开它打印的URL（通常 http://localhost:5173)以交互方式浏览和调用工具。

项目结构

sample-mcp-server/
├── server.js              # Entry point — starts the MCP server
├── client.js              # Demo client — connect and call all tools
├── package.json
│
├── config/
│   └── serverConfig.js    # Environment-variable-backed configuration
│
├── tools/
│   ├── index.js           # Tool registry — add new tools here
│   ├── timeTool.js        # get_time
│   ├── weatherTool.js     # get_weather
│   ├── fileReaderTool.js  # read_file
│   └── systemInfoTool.js  # system_info
│
├── services/
│   └── weatherService.js  # Data layer for weather (swap for a real API)
│
├── utils/
│   └── logger.js          # logInfo() / logError() helpers
│
└── docs/
    └── architecture.md    # In-depth architecture and design notes

添加自己的工具

两个步骤——不需要更改服务器核心。

步骤1——创建工具文件

// tools/helloTool.js
import { logInfo } from "../utils/logger.js";

export const helloTool = {
  name: "hello",
  description: "Greets a person by name.",
  inputSchema: {
    type: "object",
    properties: {
      name: { type: "string", description: "The person's name." },
    },
    required: ["name"],
  },
  async execute(args) {
    const { name } = args;
    if (!name || typeof name !== "string") {
      return {
        content: [{ type: "text", text: "Error: 'name' is required." }],
        isError: true,
      };
    }
    logInfo(`hello tool called for: ${name}`);
    return {
      content: [{ type: "text", text: `Hello, ${name}!` }],
    };
  },
};

第二步——注册

// tools/index.js
import { helloTool } from "./helloTool.js";

export const tools = [
  timeTool,
  weatherTool,
  fileReaderTool,
  systemInfoTool,
  helloTool,   // ← add this line
];

重新启动服务器——新工具已上线。

环境变量

所有变量都是可选的；服务器直接使用默认设置。

变量	默认值	描述
`MCP_SERVER_NAME`	`sample-mcp-server`	向客户端报告的服务器名称
`MCP_SERVER_VERSION`	`1.0.0`	向客户端报告的版本字符串
`ALLOWED_READ_BASE_PATH`	当前工作目录	此路径之外的文件被阻止 `read_file`
`WEATHER_API_KEY`	（空）	未来真实天气API占位符

例子：

ALLOWED_READ_BASE_PATH=/tmp node server.js

运作原理

请求流

┌─────────────────────────────────────────────────────────────┐
│                        MCP Client                           │
│           (Claude Desktop · MCP Inspector · client.js)      │
└────────────────────────┬────────────────────────────────────┘
                         │  JSON-RPC over stdio
                         │  (list_tools / call_tool)
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                        server.js                            │
│                                                             │
│  1. Reads config  ──►  config/serverConfig.js               │
│  2. Loads tools   ──►  tools/index.js                       │
│  3. Registers each tool with McpServer                      │
│  4. Listens on stdio for incoming requests                  │
└────────────────────────┬────────────────────────────────────┘
                         │  routes call to matching tool
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                      tools/                                 │
│                                                             │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐   │
│  │  timeTool   │  │ weatherTool  │  │  fileReaderTool  │   │
│  │  get_time   │  │  get_weather │  │    read_file     │   │
│  └─────────────┘  └──────┬───────┘  └──────────────────┘   │
│                          │                                  │
│  ┌──────────────┐        │ delegates                        │
│  │ systemInfo   │        ▼                                  │
│  │  system_info │  services/weatherService.js               │
│  └──────────────┘  (mock → swap for real API)               │
└─────────────────────────────────────────────────────────────┘
                         │  structured response
                         │  { content: [{ type, text }] }
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                        MCP Client                           │
│              receives result, shows it to user              │
└─────────────────────────────────────────────────────────────┘

逐步

客户端连接 --克劳德桌面（或 client.js)产卵 server.js 作为子进程，通过stdio进行连接。
工具发现 --客户端发送 list_tools；服务器用每个注册工具的名称、描述和输入模式进行响应。
工具调用 --客户端发送 call_tool 带有工具名称和参数。
派遣 — server.js 将调用路由到匹配工具的 execute(args) 功能。
服务层 --需要外部数据的工具（例如。 get_weather)委托给某项服务 services/，使工具处理器保持薄型。
回应 --工具返回 { content: [{ type: "text", text: "..." }] } 其流回到客户端。

如需更深入的了解，请参阅 docs/architecture.md.

故障排除

node: command not found --从以下位置安装Node.js nodejs.org.

Cannot find package '@modelcontextprotocol/sdk' --快跑 npm install 第一。

工具未显示在Claude Desktop中 --检查 args 路径在 claude_desktop_config.json 是正确的绝对路径 server.js，然后完全重新启动Claude Desktop。

Failed to spawn process: No such file or directory --Claude Desktop使用受限的PATH运行，可能找不到 node 如果它是通过Homebrew或nvm安装的。在中使用节点二进制文件的完整绝对路径 command:

which node   # prints the full path, e.g. /usr/local/opt/node@22/bin/node

然后在配置中使用该路径：

{
  "mcpServers": {
    "sample-mcp-server": {
      "command": "/usr/local/opt/node@22/bin/node",
      "args": ["/absolute/path/to/sample-mcp-server/server.js"]
    }
  }
}

read_file return“拒绝访问” --您请求的路径在允许的基目录之外。集 ALLOWED_READ_BASE_PATH 如果您需要访问其他目录。

了解更多

许可证

麻省理工学院