AI导哈

MCP协议服务器

一个简单的自包含MCP（模型上下文协议）服务器，提供时间获取、日期格式化、数学计算、时区信息、随机数生成和Shell命令执行等基本实用功能。

  • by TrueBad0ur
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 TrueBad0ur/mcp-simple-server

使用说明

简单MCP服务器

一个简单的、自包含的MCP（模型上下文协议）服务器，具有基本的实用功能。 无需API密钥，无需信用卡，无需外部依赖！

特性

  • 获取当前时间 -UTC和当地时间
  • 获取当前日期 -多种日期格式
  • 计算 -基本数学运算
  • 时区信息 -获取时区信息
  • 生成随机数 -在一定范围内生成随机数
  • 执行Shell命令 -运行shell命令并获取输出
  • 综合录井 -所有请求都记录到本地文件进行监控

完整安装指南

步骤1：启动服务器

  1. 导航到项目目录：

    cd mcp

  2. 构建并启动Docker容器：

    docker compose up --build

    这将：

    • 构建Docker镜像
    • 启动容器
    • 暴露端口8000上的服务器

  3. 验证服务器是否正在运行：

    # Check container status
docker compose ps

# Check logs (in another terminal)
docker compose logs -f mcp-server

# Test health endpoint (replace <remote-server-ip> with your server IP)
curl -H "X-API-Key: your-secure-api-key-here" http://<remote-server-ip>:8000/health

    您应该看到：

    • 容器状态： Up
    • 日志显示： Uvicorn running on http://0.0.0.0:8000
    • 健康检查返回： {"status": "healthy"}

步骤2：配置游标IDE

  1. 打开光标IDE

  2. 打开命令选项板：

    • 按 Ctrl+Shift+P （Windows/Linux）或 Cmd+Shift+P （Mac）
    • 类型： MCP Settings 或 MCP: Configure

  3. 添加新的MCP服务器：

    • 点击“添加新”或“+”按钮
    • 系统将提示您添加服务器配置

  4. 输入服务器配置：

    选项A：手动输入

    • 名字: simple-utils-server
    • 统一资源定位符: http://<remote-server-ip>:8000/sse
      • 替换 <remote-server-ip> 使用您的实际服务器IP地址
      • 例子： http://192.168.1.100:8000/sse 或 http://example.com:8000/sse
    • 运输: sse 或 SSE
    • 标头：添加 X-API-Key: your-secure-api-key-here

    选项B：从mcp.json导入

    • 打开 mcp.json 此存储库中的文件
    • 复制全部内容
    • 将其粘贴到MCP设置配置中
    • 重要：替换 <remote-server-ip> 使用您的实际服务器IP地址
    • 配置应该如下所示：
      {
  "mcpServers": {
    "simple-utils-server": {
      "url": "http://<remote-server-ip>:8000/sse",
      "transport": "sse",
      "headers": {
        "X-API-Key": "your-secure-api-key-here"
      }
    }
  }
}

  5. 保存配置：

    • 点击“保存”或按 Enter
    • 游标将自动连接到服务器

  6. 验证连接：

    • 在Cursor的状态栏中查找MCP服务器状态
    • 它应该显示： simple-utils-server: Connected
    • 您应该看到加载了6个工具

步骤3：测试连接

  1. 在Cursor的聊天中，尝试问：

    "What time is it right now?"

  2. AI应该：

    • 自动使用 get_current_time 工具
    • 返回当前时间信息

  3. 尝试其他命令：

    "Calculate sqrt(144) + 5"
"Run the command 'echo hello world'"
"Get today's date"

连接问题疑难解答

  • 服务器未连接？

    • 验证服务器是否正在运行： docker compose ps
    • 检查服务器日志： docker compose logs mcp-server
    • 直接测试服务器： curl http://<remote-server-ip>:8000/health

  • 连接被拒绝？

    • 检查防火墙是否允许端口8000
    • 验证IP地址是否正确
    • 确保服务器正在侦听 0.0.0.0 （默认情况下为）

  • 工具未加载？

    • 完全重新启动游标
    • 检查MCP设置配置是否正确
    • 验证URL是否包含 /sse 在最后

安全

MCP服务器要求对所有请求进行API密钥身份验证。

API密钥验证

设置 MCP_API_KEY 环境变量：

export MCP_API_KEY="your-secure-api-key-here"

所有请求都必须在 X-API-Key 头球

curl -H "X-API-Key: your-secure-api-key-here" http://your-server:8000/health

快速入门（摘要）

# 1. Start server
docker compose up --build

# 2. In Cursor: Ctrl+Shift+P -> MCP Settings -> Add New
#    URL: http://<remote-server-ip>:8000/sse
#    Transport: sse

# 3. Test: Ask "What time is it?"

可用工具

1.get_current_time

获取UTC和本地时区的当前时间。

例子：

{
  "tool": "get_current_time",
  "arguments": {}
}

2.get_current_date

获取各种格式的当前日期。

例子：

{
  "tool": "get_current_date",
  "arguments": {
    "format": "iso"
  }
}

格式: iso, us, european, unix

3.计算

进行基本的数学计算。

例子：

{
  "tool": "calculate",
  "arguments": {
    "expression": "sqrt(16) + 2 * 3"
  }
}

支持的功能: sqrt, sin, cos, tan, log, log10, exp, pow, abs, round, floor, ceil, min, max, sum 常量: pi, e

4.获取时区信息

获取时区信息。

例子：

{
  "tool": "get_timezone_info",
  "arguments": {
    "timezone": "America/New_York"
  }
}

5.发电机随机数

在指定范围内生成随机数。

例子：

{
  "tool": "generate_random_number",
  "arguments": {
    "min_value": 1,
    "max_value": 100,
    "count": 5
  }
}

参数：

  • min_value （可选）：最小值（默认值：1）
  • max_value （可选）：最大值（默认值：100）
  • count （可选）：要生成的随机数（默认值：1，最大值：100）

退货： 带范围信息的随机数

6.执行命令

执行shell命令并返回输出。 警告：请谨慎使用，因为这可能会执行任意命令。

例子：

{
  "tool": "execute_command",
  "arguments": {
    "command": "ls -la",
    "working_directory": "/tmp",
    "timeout": 30
  }
}

参数：

  • command （必需）：要执行的Shell命令
  • working_directory （可选）：命令的工作目录
  • timeout （可选）：超时秒数（默认值：30）

命令示例：

  • "ls -la" -列出文件
  • "echo hello world" -打印文本
  • "python --version" -检查Python版本
  • "pwd" -打印工作目录
  • "date" -获取当前日期

测试

卷曲测试：

# Health check (replace <remote-server-ip> with your server IP)
curl http://<remote-server-ip>:8000/health

# Root endpoint
curl http://<remote-server-ip>:8000/

测试MCP工具（直接使用HTTP）：

服务器使用SSE进行MCP协议，但您可以测试基本端点。

防火墙配置

如果从VPS外部访问，请打开端口8000：

# Ubuntu/Debian
sudo ufw allow 8000/tcp

# CentOS/RHEL
sudo firewall-cmd --add-port=8000/tcp --permanent
sudo firewall-cmd --reload

发展

在本地运行（不使用Docker）：

# Install dependencies
pip install -r requirements.txt

# Run the server
python server.py

服务器将在以下时间可用 http://<remote-server-ip>:8000

项目结构

mcp/
├── server.py          # HTTP/SSE MCP server (for remote use)
├── requirements.txt   # Python dependencies
├── Dockerfile         # Docker image definition
├── docker-compose.yml # Docker compose configuration
└── README.md          # This file

故障排除

  1. 容器无法启动：检查日志 docker compose logs mcp-server

  2. 端口已在使用中：更改端口 docker-compose.yml:

    ports:
  - "8001:8000"  # Use 8001 instead

  3. 无法从游标连接:

    • 验证防火墙是否允许端口8000
    • 检查容器是否正在运行： docker compose ps
    • 验证URL是否正确： http://<remote-server-ip>:8000/sse

  4. 连接被拒绝:

    • 确保服务器正在侦听 0.0.0.0 （默认情况下为）
    • 检查VPS防火墙规则

安全注意事项

  • 服务器为所有源启用了CORS（用于测试）
  • 对于生产，请考虑：
    • 限制CORS来源
    • 添加身份验证
    • 使用HTTPS和反向代理（nginx/traefik）
    • 限制防火墙对受信任IP的访问

有用的命令

# View logs
docker compose logs -f mcp-server

# Restart the server
docker compose restart mcp-server

# Stop the server
docker compose down

# Rebuild and restart
docker compose up -d --build

# Check container status
docker compose ps

没有外部依赖！

此服务器仅使用：

  • Python标准库（日期时间、数学、json）
  • MCP SDK（用于协议）
  • FastAPI/Uvicorn（用于HTTP服务器）

日志记录

服务器会自动将所有请求记录到本地文本文件中(requests_log.txt)综合信息包括：

  • 客户信息：IP地址、用户代理、标头等。
  • 请求详细信息：工具名、参数、时间戳
  • 响应数据：完整的响应内容，成功/失败状态
  • 察看连接信息：请求ID、服务器版本、处理时间

日志文件格式

每个日志条目包括：

  • 唯一请求ID
  • UTC时间戳
  • JSON格式的完整请求/响应数据
  • 成功/失败指标

查看日志

# View recent logs (on host machine)
tail -f logs/requests_log.txt

# Search for specific tool calls
grep "tool_name" logs/requests_log.txt

# Count total requests
grep "REQUEST LOG ENTRY" logs/requests_log.txt | wc -l

注： 日志文件会自动持久化在主机上 ./logs/ 使用Docker卷的目录。这意味着日志在容器重启后仍然有效，即使在容器停止后也可以访问。日志包含敏感信息-出于安全和调试目的对其进行监控。

没有外部依赖！

此服务器仅使用：

  • Python标准库（日期时间、数学、json、随机、os、sys、uuid）
  • MCP SDK（用于协议）
  • FastAPI/Uvicorn（用于HTTP服务器）

无需API密钥，无需信用卡，无需外部服务！

相关 MCP