从零构建 MCP 服务器：
让 Claude 拥有你的自定义工具集

初始化项目

用 uv 创建隔离的 Python 项目，避免污染全局环境：

# 创建项目目录
uv init dev-assistant-mcp
cd dev-assistant-mcp

# 安装 MCP SDK（含 FastMCP）
uv add "mcp[cli]" httpx

# 验证安装
uv run python -c "import mcp; print(mcp.__version__)"

创建第一个工具（Hello World）

新建 server.py，先写最简单的工具验证环境正常：

# server.py
from mcp.server.fastmcp import FastMCP

# 初始化服务器，名称会显示在 Claude 工具列表里
mcp = FastMCP("dev-assistant")

@mcp.tool()
def greet(name: str) -> str:
    """向指定用户打招呼（测试用工具）"""
    return f"你好，{name}！我是你的开发助手 MCP 服务器。"

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

用 MCP Inspector 测试（强烈建议，能节省大量后续调试时间）：

npx @modelcontextprotocol/inspector uv run server.py

浏览器打开 http://localhost:5173，点击 Tools → greet → Run Tool，看到响应说明服务器正常。

添加 Hacker News 查询工具

这才是真正有用的工具——实时查询 HN 热点，并发请求加速：

# server.py（续接步骤2）
import httpx
import json
import asyncio

HN_API = "https://hacker-news.firebaseio.com/v0"

@mcp.tool()
async def get_hn_top_stories(limit: int = 5) -> str:
    """
    获取 Hacker News 当前热门文章列表。

    Args:
        limit: 返回数量，默认 5，最多 20

    Returns:
        格式化的热门文章列表（标题、URL、分数、评论数）
    """
    limit = min(limit, 20)

    async with httpx.AsyncClient(timeout=10.0) as client:
        resp = await client.get(f"{HN_API}/topstories.json")
        story_ids = resp.json()[:limit]

        # 并发获取文章详情
        tasks = [client.get(f"{HN_API}/item/{sid}.json") for sid in story_ids]
        responses = await asyncio.gather(*tasks)

    stories = []
    for r in responses:
        s = r.json()
        stories.append({
            "title": s.get("title", "无标题"),
            "url":   s.get("url", f"https://news.ycombinator.com/item?id={s['id']}"),
            "score": s.get("score", 0),
            "comments": s.get("descendants", 0),
        })

    lines = [f"Hacker News 今日热门（前 {limit} 条）：\n"]
    for i, s in enumerate(stories, 1):
        lines.append(f"{i}. {s['title']}")
        lines.append(f"   🔗 {s['url']}")
        lines.append(f"   ⬆️ {s['score']} 分 | 💬 {s['comments']} 评论\n")

    return "\n".join(lines)

添加 Shell 命令执行工具

让 Claude 能在你的机器上执行安全的 Shell 命令（带白名单保护）：

# server.py（续）
import subprocess
import shlex

# 允许的命令白名单（只读/安全操作）
ALLOWED_COMMANDS = {
    "ls", "cat", "echo", "pwd", "git",
    "python3", "node", "bun", "grep", "find"
}

@mcp.tool()
def run_shell(command: str, working_dir: str = ".") -> str:
    """
    在本地执行 Shell 命令（仅限白名单命令）。

    Args:
        command: 要执行的 shell 命令
        working_dir: 工作目录，默认当前目录
    """
    parts = shlex.split(command)
    if not parts:
        return "错误：命令为空"

    cmd_name = parts[0]
    if cmd_name not in ALLOWED_COMMANDS:
        return f"错误：'{cmd_name}' 不在允许列表。允许：{', '.join(sorted(ALLOWED_COMMANDS))}"

    try:
        result = subprocess.run(
            parts,
            capture_output=True,
            text=True,
            timeout=30,
            cwd=working_dir,
        )
        output = result.stdout
        if result.returncode != 0:
            output += f"\n[退出码 {result.returncode}]\n{result.stderr}"
        return output or "(命令执行成功，无输出)"

    except subprocess.TimeoutExpired:
        return "错误：命令执行超时（>30秒）"
    except Exception as e:
        return f"错误：{type(e).__name__}: {e}"

添加资源（Resources）

资源让 Claude 能"读取"你的数据，适合只读场景：

# server.py（续）
import os
from pathlib import Path

@mcp.resource("project://readme")
def get_project_readme() -> str:
    """当前目录的 README 文件内容"""
    readme = Path("README.md")
    if readme.exists():
        return readme.read_text(encoding="utf-8")
    return "（当前目录没有 README.md）"

@mcp.resource("system://info")
def get_system_info() -> str:
    """获取系统基本信息（OS、Python 版本、当前目录）"""
    import platform
    info = {
        "os":     platform.system(),
        "python": platform.python_version(),
        "cwd":    os.getcwd(),
        "home":   str(Path.home()),
    }
    return json.dumps(info, ensure_ascii=False, indent=2)

接入 Claude Desktop

找到配置文件位置：

# macOS
open ~/Library/Application\ Support/Claude/

# Windows（在资源管理器地址栏输入）
%APPDATA%\Claude\

编辑 claude_desktop_config.json（不存在则新建）：

{
  "mcpServers": {
    "dev-assistant": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/Users/yourname/dev-assistant-mcp",
        "python",
        "/Users/yourname/dev-assistant-mcp/server.py"
      ]
    }
  }
}

把 /Users/yourname 替换为你的实际路径，然后完全重启 Claude Desktop。在聊天框下方看到工具图标 🔨 表示连接成功。

接入 Claude Code

Claude Code 使用项目级配置文件：

# 在你的工作目录执行
mkdir -p .claude
cat > .claude/settings.json << 'EOF'
{
  "mcpServers": {
    "dev-assistant": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/Users/yourname/dev-assistant-mcp",
        "python",
        "/Users/yourname/dev-assistant-mcp/server.py"
      ]
    }
  }
}
EOF

在 Claude Code 中输入 /mcp 确认服务器已连接，或直接问："用 dev-assistant 查一下 HN 今天最热的 5 条新闻"。