mcp-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MCP Server Building Skill

MCP 服务器构建技能

You now have expertise in building MCP (Model Context Protocol) servers. MCP enables Claude to interact with external services through a standardized protocol.

你现在具备构建MCP（Model Context Protocol）服务器的专业能力。MCP允许Claude通过标准化协议与外部服务进行交互。

What is MCP?

什么是MCP？

MCP servers expose:

Tools: Functions Claude can call (like API endpoints)
Resources: Data Claude can read (like files or database records)
Prompts: Pre-built prompt templates

MCP服务器对外提供：

工具：Claude可以调用的函数（如API端点）
资源：Claude可以读取的数据（如文件或数据库记录）
提示词：预构建的提示词模板

Quick Start: Python MCP Server

快速开始：Python MCP服务器

1. Project Setup

1. 项目设置

bash

undefined

bash

undefined

Create project

mkdir my-mcp-server && cd my-mcp-server python3 -m venv venv && source venv/bin/activate

Install MCP SDK

pip install mcp

undefined

pip install mcp

undefined

2. Basic Server Template

2. 基础服务器模板

python

#!/usr/bin/env python3
"""my_server.py - A simple MCP server"""

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

python

#!/usr/bin/env python3
"""my_server.py - A simple MCP server"""

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

Create server instance

server = Server("my-server")

Define a tool

@server.tool() async def hello(name: str) -> str: """Say hello to someone.

Args:
    name: The name to greet
"""
return f"Hello, {name}!"

@server.tool() async def add_numbers(a: int, b: int) -> str: """Add two numbers together.

Args:
    a: First number
    b: Second number
"""
return str(a + b)

@server.tool() async def hello(name: str) -> str: """Say hello to someone.

Args:
    name: The name to greet
"""
return f"Hello, {name}!"

@server.tool() async def add_numbers(a: int, b: int) -> str: """Add two numbers together.

Args:
    a: First number
    b: Second number
"""
return str(a + b)

Run server

async def main(): async with stdio_server() as (read, write): await server.run(read, write)

if name == "main": import asyncio asyncio.run(main())

undefined

async def main(): async with stdio_server() as (read, write): await server.run(read, write)

if name == "main": import asyncio asyncio.run(main())

undefined

3. Register with Claude

3. 向Claude注册

Add to

~/.claude/mcp.json

json

{
  "mcpServers": {
    "my-server": {
      "command": "python3",
      "args": ["/path/to/my_server.py"]
    }
  }
}

添加到

~/.claude/mcp.json

：

json

{
  "mcpServers": {
    "my-server": {
      "command": "python3",
      "args": ["/path/to/my_server.py"]
    }
  }
}

TypeScript MCP Server

TypeScript MCP服务器

1. Setup

1. 设置

bash

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk

bash

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk

2. Template

2. 模板

typescript

// src/index.ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({
  name: "my-server",
  version: "1.0.0",
});

// Define tools
server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "hello",
      description: "Say hello to someone",
      inputSchema: {
        type: "object",
        properties: {
          name: { type: "string", description: "Name to greet" },
        },
        required: ["name"],
      },
    },
  ],
}));

server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "hello") {
    const name = request.params.arguments.name;
    return { content: [{ type: "text", text: `Hello, ${name}!` }] };
  }
  throw new Error("Unknown tool");
});

// Start server
const transport = new StdioServerTransport();
server.connect(transport);

typescript

// src/index.ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({
  name: "my-server",
  version: "1.0.0",
});

// Define tools
server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "hello",
      description: "Say hello to someone",
      inputSchema: {
        type: "object",
        properties: {
          name: { type: "string", description: "Name to greet" },
        },
        required: ["name"],
      },
    },
  ],
}));

server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "hello") {
    const name = request.params.arguments.name;
    return { content: [{ type: "text", text: `Hello, ${name}!` }] };
  }
  throw new Error("Unknown tool");
});

// Start server
const transport = new StdioServerTransport();
server.connect(transport);

Advanced Patterns

高级模式

External API Integration

外部API集成

python

import httpx
from mcp.server import Server

server = Server("weather-server")

@server.tool()
async def get_weather(city: str) -> str:
    """Get current weather for a city."""
    async with httpx.AsyncClient() as client:
        resp = await client.get(
            f"https://api.weatherapi.com/v1/current.json",
            params={"key": "YOUR_API_KEY", "q": city}
        )
        data = resp.json()
        return f"{city}: {data['current']['temp_c']}C, {data['current']['condition']['text']}"

python

import httpx
from mcp.server import Server

server = Server("weather-server")

@server.tool()
async def get_weather(city: str) -> str:
    """Get current weather for a city."""
    async with httpx.AsyncClient() as client:
        resp = await client.get(
            f"https://api.weatherapi.com/v1/current.json",
            params={"key": "YOUR_API_KEY", "q": city}
        )
        data = resp.json()
        return f"{city}: {data['current']['temp_c']}C, {data['current']['condition']['text']}"

Database Access

数据库访问

python

import sqlite3
from mcp.server import Server

server = Server("db-server")

@server.tool()
async def query_db(sql: str) -> str:
    """Execute a read-only SQL query."""
    if not sql.strip().upper().startswith("SELECT"):
        return "Error: Only SELECT queries allowed"

    conn = sqlite3.connect("data.db")
    cursor = conn.execute(sql)
    rows = cursor.fetchall()
    conn.close()
    return str(rows)

python

import sqlite3
from mcp.server import Server

server = Server("db-server")

@server.tool()
async def query_db(sql: str) -> str:
    """Execute a read-only SQL query."""
    if not sql.strip().upper().startswith("SELECT"):
        return "Error: Only SELECT queries allowed"

    conn = sqlite3.connect("data.db")
    cursor = conn.execute(sql)
    rows = cursor.fetchall()
    conn.close()
    return str(rows)

Resources (Read-only Data)

资源（只读数据）

python

@server.resource("config://settings")
async def get_settings() -> str:
    """Application settings."""
    return open("settings.json").read()

@server.resource("file://{path}")
async def read_file(path: str) -> str:
    """Read a file from the workspace."""
    return open(path).read()

python

@server.resource("config://settings")
async def get_settings() -> str:
    """Application settings."""
    return open("settings.json").read()

@server.resource("file://{path}")
async def read_file(path: str) -> str:
    """Read a file from the workspace."""
    return open(path).read()

Testing

测试

bash

undefined

bash

undefined

Test with MCP Inspector

npx @anthropics/mcp-inspector python3 my_server.py

Or send test messages directly

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | python3 my_server.py

undefined

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | python3 my_server.py

undefined

Best Practices

最佳实践

Clear tool descriptions: Claude uses these to decide when to call tools
Input validation: Always validate and sanitize inputs
Error handling: Return meaningful error messages
Async by default: Use async/await for I/O operations
Security: Never expose sensitive operations without auth
Idempotency: Tools should be safe to retry

清晰的工具描述：Claude会根据这些描述决定何时调用工具
输入验证：始终验证并清理输入
错误处理：返回有意义的错误信息
默认使用异步：对I/O操作使用async/await
安全性：未经授权绝不暴露敏感操作
幂等性：工具应可安全重试