MCP Server Setup Documentation

MCP 服务设置文档

概述

本指南详细介绍如何设置与 Claude Desktop 集成的模型控制协议（MCP）服务。MCP 服务可以扩展 Claude 的能力，使其能够与外部系统和 API 交互，包括 AWS 服务和 GitHub。

前提条件

• 已安装 Python 3.8+
• Claude Desktop 应用程序
• 已安装 uv 包管理器
• 具备 Python 和命令行操作的基础知识

安装步骤

1. 安装所需软件包

首先，确保已安装必要的软件包：

# Install UV if not already installed
pip install uv

# Install MCP and dependencies using UV
uv add mcp[cli] pygithub boto3

2. 创建服务脚本

在所需目录中创建名为 server.py 的文件，并在其中实现自定义函数。

server.py 的示例结构：

from mcp.server.fastmcp import FastMCP
import boto3
from dotenv import load_dotenv
from github import Github

load_dotenv()

# Initialize MCP server
mcp = FastMCP("Custom MCP Server", "0.1.0")

# Define your custom functions
@mcp.tool()
def fetch_aws_ec2_instances(region_name="us-east-1"):
    """
    Fetches and describes all EC2 instances in the specified AWS region.
    :param region_name: The name of the AWS region (e.g., 'us-east-1')
    :return: A list of EC2 instances in the specified region.
    """
    ec2 = boto3.client('ec2', region_name=region_name)
    return ec2.describe_instances()

# Add more custom tools as needed...

3. 测试服务

连接到 Claude Desktop 之前，先测试服务，确保其正常运行：

uv run mcp install server.py

你应该会看到表明服务正在运行的输出，通常显示端口为 8000。

4. 配置 Claude Desktop

1. 打开 Claude Desktop 应用程序
2. 前往 File > Settings > Developer > Edit Config
3. 使用 MCP 服务的详细信息更新配置：

{
  "mcpServers": {
    "Custom MCP Server": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp[cli], pygithub, boto3",
        "mcp",
        "run",
        "/full/path/to/your/server.py"
      ]
    }
  }
}

重要配置说明：

• 将 /full/path/to/your/server.py 替换为 server.py 文件的绝对路径
• 将其他所需软件包添加到 --with 参数中
• 你可以将 "Custom MCP Server" 重命名为任意名称

5. 启用并启动 MCP 服务

1. 在 Claude Desktop 中，前往 File > Settings > Developer
2. 启用已配置的 MCP 服务
3. Claude 将尝试连接到你的服务

高级配置

环境变量

如需安全地处理 API 密钥和凭据，请使用 .env 文件：

在与 server.py 相同的目录中创建 .env 文件：

.env 文件

AWS_ACCESS_KEY_ID=your_access_key_here AWS_SECRET_ACCESS_KEY=your_secret_key_here GITHUB_TOKEN=your_github_token_here

根据需要添加其他环境变量

添加自定义依赖项

如果你的服务需要其他 Python 软件包，请将其添加到 Claude Desktop 配置中的 --with 参数：

"args": [
  "run",
  "--with",
  "mcp[cli], pygithub, boto3, pandas, requests",
  "mcp",
  "run",
  "/path/to/server.py"
]

错误处理

在服务函数中实现适当的错误处理：

@server.function()
def some_function(param):
    try:
        # Function logic
        return result
    except Exception as e:
        return {"error": str(e), "status": "failed"}

故障排除

常见问题及解决方案

1. 连接被拒绝

   • 确保服务正在运行
   • 检查端口是否已被占用
   • 检查防火墙设置

2. 导入错误

   • 确认所有依赖项都已包含在 --with 参数中
   • 尝试手动安装软件包：uv pip install [package-name]

3. 权限错误

   • 检查 server.py 的文件权限
   • 确保 AWS/GitHub 凭据可用

4. 找不到函数

   • 确认函数已使用 @server.function() 正确装饰
   • 重启服务和 Claude Desktop

示例用例

AWS 资源管理

@server.function()
def describe_ec2_instances(region_name="us-east-1"):
    ec2 = boto3.client('ec2', region_name=region_name)
    return ec2.describe_instances()

@server.function()
def start_ec2_instance(instance_id, region_name="us-east-1"):
    ec2 = boto3.client('ec2', region_name=region_name)
    return ec2.start_instances(InstanceIds=[instance_id])

GitHub 集成

@server.function()
def fetch_github_repo_info(repo):
    g = Github(os.getenv("GITHUB_TOKEN"))
    repo = g.get_repo(repo)
    return {
        "name": repo.name,
        "description": repo.description,
        "stars": repo.stargazers_count,
        "forks": repo.forks_count
    }

安全注意事项

• 切勿在 server.py 文件中硬编码凭据
• 使用环境变量存储敏感信息
• 考虑为 MCP 服务实现身份验证
• 谨慎选择通过 MCP 服务公开的函数

资源

• MCP 文档