MCP Server 开发教程：手写你的第一个 MCP 服务器（2026）

# 新建项目
uv init ticket-server
cd ticket-server

# 创建并激活虚拟环境
uv venv
source .venv/bin/activate      # Windows 用 .venv\Scripts\activate

# 安装 MCP SDK
uv add "mcp[cli]"

# 创建服务器文件
touch server.py

from mcp.server import MCPServer

# 初始化服务器实例，名字会显示在客户端里
mcp = MCPServer("ticket")

# 这里用假数据演示，实际换成你的数据库查询 / 内部 API 调用
TICKETS = {
    "T-1001": {"title": "登录页验证码不显示", "status": "处理中", "owner": "张伟"},
    "T-1002": {"title": "导出 Excel 乱码", "status": "已关闭", "owner": "李娜"},
}


@mcp.tool()
async def get_ticket(ticket_id: str) -> str:
    """根据工单号查询工单详情。

    Args:
        ticket_id: 工单编号，形如 T-1001
    """
    ticket = TICKETS.get(ticket_id.upper())
    if not ticket:
        return f"没有找到工单 {ticket_id}"
    return (
        f"工单号：{ticket_id}\n"
        f"标题：{ticket['title']}\n"
        f"状态：{ticket['status']}\n"
        f"负责人：{ticket['owner']}"
    )


@mcp.tool()
async def list_open_tickets() -> str:
    """列出所有未关闭的工单。"""
    rows = [
        f"{tid}: {t['title']}（{t['owner']}）"
        for tid, t in TICKETS.items()
        if t["status"] != "已关闭"
    ]
    return "\n".join(rows) if rows else "当前没有未关闭工单"


if __name__ == "__main__":
    mcp.run(transport="stdio")

mkdir ticket-server && cd ticket-server
npm init -y

# 官方包名在 2026 年改过，注意是 /server 不是老的 /sdk
npm install @modelcontextprotocol/server zod
npm install -D @types/node typescript

mkdir src && touch src/index.ts

{
  "type": "module",
  "bin": {
    "ticket-server": "./build/index.js"
  },
  "scripts": {
    "build": "tsc && chmod 755 build/index.js"
  },
  "files": ["build"]
}

import { McpServer } from "@modelcontextprotocol/server";
import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
import { z } from "zod";

const server = new McpServer({
  name: "ticket",
  version: "1.0.0",
});

const TICKETS: Record<string, { title: string; status: string; owner: string }> = {
  "T-1001": { title: "登录页验证码不显示", status: "处理中", owner: "张伟" },
  "T-1002": { title: "导出 Excel 乱码", status: "已关闭", owner: "李娜" },
};

server.registerTool(
  "get_ticket",
  {
    description: "根据工单号查询工单详情",
    inputSchema: z.object({
      ticket_id: z.string().describe("工单编号，形如 T-1001"),
    }),
  },
  async ({ ticket_id }) => {
    const ticket = TICKETS[ticket_id.toUpperCase()];
    if (!ticket) {
      return { content: [{ type: "text", text: `没有找到工单 ${ticket_id}` }] };
    }
    return {
      content: [
        {
          type: "text",
          text: `工单号：${ticket_id}\n标题：${ticket.title}\n状态：${ticket.status}\n负责人：${ticket.owner}`,
        },
      ],
    };
  }
);

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  // 注意：日志必须走 stderr，写 stdout 会污染 JSON-RPC 通道
  console.error("Ticket MCP Server running on stdio");
}

main().catch((error) => {
  console.error("Fatal error in main():", error);
  process.exit(1);
});

# 加一个本地 stdio 服务器（Python 版）
claude mcp add --transport stdio ticket -- uv --directory /绝对路径/ticket-server run server.py

# TypeScript 版（注意指向编译后的 build/index.js）
claude mcp add --transport stdio ticket -- node /绝对路径/ticket-server/build/index.js

# 需要传密钥时用 --env
claude mcp add --env TICKET_API_KEY=你的密钥 --transport stdio ticket -- node /绝对路径/build/index.js

# 远程 HTTP 服务器
claude mcp add --transport http ticket https://mcp.your-company.com/mcp

# 查看状态：会显示 ✔ Connected / ✘ Failed to connect
claude mcp list
claude mcp get ticket

# 写进 .mcp.json，提交到仓库全组共享
claude mcp add --transport stdio ticket --scope project -- node ./build/index.js

{
  "mcpServers": {
    "ticket": {
      "command": "node",
      "args": ["/绝对路径/ticket-server/build/index.js"],
      "env": {
        "TICKET_API_KEY": "你的密钥"
      }
    }
  }
}

# 调试 stdio 服务器：把启动命令跟在后面
npx @modelcontextprotocol/inspector node build/index.js
npx @modelcontextprotocol/inspector uv --directory . run server.py

# 调试已经跑起来的 HTTP 服务器
npx @modelcontextprotocol/inspector --url http://localhost:3000