AI导哈

模型上下文协议服务器

一个通用的模型上下文协议（MCP）服务器，为Claude Code和Claude Desktop提供工具支持。

  • by tim-akkio
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 AkkioTim/mcp-server

使用说明

MCP服务器框架

一个通用的模型上下文协议（MCP）服务器，为Claude Code和Claude Desktop提供工具。

快速开始

# Install dependencies
cd mcp-server
pip install -r requirements.txt

# Test the server runs (Ctrl+C to stop)
PYTHONPATH=src python -m mcp_server.server

项目结构

mcp-server/
├── src/mcp_server/
│   ├── server.py          # Main FastMCP server
│   ├── config.py          # Environment-based configuration
│   └── tools/
│       ├── __init__.py    # Tool registry
│       ├── echo_tool.py   # Example: basic echo tools
│       ├── datetime_tool.py  # Example: date/time utilities
│       └── file_tool.py   # Example: file operations
├── configs/               # Client configuration templates
└── requirements.txt

配置

服务器是通过环境变量配置的：

变量 描述 默认值
MCP_SERVER_NAME 服务器的显示名称 mcp-server
MCP_LOG_LEVEL 日志记录级别（调试、信息、警告、错误） INFO
MCP_ALLOWED_PATHS 文件工具的逗号分隔路径 （无）
MCP_CUSTOM_VAR_* 可通过配置访问自定义变量 （无）

包含的工具

回声工具

  • echo -回显消息
  • echo_uppercase -大写回声
  • echo_reverse -回声反转

DateTime工具

  • get_current_time -获取当前UTC时间
  • get_timestamp -获取当前Unix时间戳
  • parse_timestamp -将时间戳转换为可读格式
  • time_difference -计算两个时间戳之间的时间

文件工具（必需 MCP_ALLOWED_PATHS)

  • list_directory -列出目录内容
  • read_file -读取文件内容
  • get_file_info -获取文件/目录元数据
  • get_allowed_paths -显示已配置的允许路径

设置客户端

克劳德桌面版

  1. 打开 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）
  2. 添加您的服务器配置：
{
  "mcpServers": {
    "my-mcp-server": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "/full/path/to/mcp-server",
      "env": {
        "PYTHONPATH": "/full/path/to/mcp-server/src",
        "MCP_ALLOWED_PATHS": "/Users/you/Documents"
      }
    }
  }
}
  1. 完全重新启动克劳德桌面（Cmd+Q，然后重新启动）

克劳德代码

创建 .mcp.json 在项目根目录中：

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "${workspaceFolder}/mcp-server",
      "env": {
        "PYTHONPATH": "${workspaceFolder}/mcp-server/src",
        "MCP_ALLOWED_PATHS": "${workspaceFolder}"
      }
    }
  }
}

添加新工具

  1. 在中创建新文件 src/mcp_server/tools/:
# src/mcp_server/tools/my_tool.py
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from mcp.server.fastmcp import FastMCP
    from ..config import ServerConfig


def register(mcp: "FastMCP", config: "ServerConfig") -> None:
    """Register my tools with the server."""

    @mcp.tool()
    def my_function(param: str, count: int = 1) -> str:
        """
        Description shown to Claude.

        Args:
            param: What this parameter does
            count: Optional count with default

        Returns:
            What the tool returns
        """
        return f"Result: {param} x {count}"
  1. 在中注册 src/mcp_server/tools/__init__.py:
def register_all_tools(mcp: "FastMCP", config: "ServerConfig") -> None:
    from . import echo_tool, datetime_tool, file_tool, my_tool  # Add import

    echo_tool.register(mcp, config)
    datetime_tool.register(mcp, config)
    file_tool.register(mcp, config)
    my_tool.register(mcp, config)  # Add registration
  1. 重新启动Claude Desktop/Code以获取新工具。

工具设计指南

  1. 清除文档字符串：描述和参数文档发送给Claude
  2. 键入提示：所有参数和返回都需要类型提示（定义JSON模式）
  3. 返回字符串：工具应返回字符串结果以获得最佳兼容性
  4. 错误处理：返回用户友好的错误消息，而不是引发异常
  5. 使用配置：访问 config 用于特定环境的设置（如允许的路径）

故障排除

服务器无法启动：

  • 确保 PYTHONPATH 包括 src 目录
  • 检查一下 mcp 软件包已安装： pip install mcp[cli]

Claude中未出现的工具：

  • 验证配置JSON是否有效
  • 检查 cwd 路径正确
  • 完全重新启动克劳德桌面（Mac上的Cmd+Q）

文件工具返回“不在允许的目录中”：

  • 集 MCP_ALLOWED_PATHS 以逗号分隔的目录路径
  • 路径必须是绝对的

依赖项

  • Python 3.10+
  • mcp[cli]>=1.0.0

相关 MCP