AI导哈

MCP服务器模板

一个本地MCP服务器模板，用于构建Claude集成，所有令牌和凭证都保留在您的机器上。

  • by stevesimpson418
  • Shell
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 stevesimpson418/mcp-repo-template

使用说明

MCP服务器模板

本地人 主控程序 用于构建Claude集成的服务器模板。通过stdio在本地运行 传输——所有令牌和凭据都保留在您的计算机上。

先决条件

  • Python 3.12+
  • 紫外线 用于依赖关系管理

快速开始

# Clone the repo
git clone https://github.com/stevesimpson418/mcp-repo-template.git
cd mcp-server-template

# Install dependencies (creates .venv/ in the project directory)
uv sync

# Configure environment
cp .env.example .env
# Edit .env with your API credentials

紫外线新手？ uv sync 读取 pyproject.toml，创建了一个 .venv/ virtualenv内部 项目文件夹，并将所有依赖项安装到其中。您不需要激活它-- uv run <command> 自动处理。

添加到Claude桌面

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

提示： 跑 uv run which python 从项目目录中获取 command.

{
  "mcpServers": {
    "my-server": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "mcp_server_template.server"],
      "env": {
        "API_TOKEN": "your_token_here"
      }
    }
  }
}

添加到Claude代码CLI

使用 claude mcp add 注册服务器的命令。这适用于任何目录。

claude mcp add --scope user my-server \
  --transport stdio \
  --env API_TOKEN=your_token_here \
  -- /path/to/my-server/.venv/bin/python -m mcp_server_template.server

替换 /path/to/my-server 使用克隆仓库的实际路径。

提示： 跑 uv run which python 从项目目录中获取确切信息 .venv/bin/python 命令的路径。

这 --scope user 标志保存到 ~/.claude.json 因此，服务器在所有项目中都是可用的。 没有它，命令默认为本地作用域（绑定到您运行它的任何目录）。 要将其范围改为单个项目，请使用 --scope project 它写入 .mcp.json 在 项目根。

要验证服务器是否已注册：

claude mcp list

添加后重新启动Claude Code。工具应出现在 /mcp 菜单。

注： Claude Code CLI使用与Claude Desktop不同的配置。这 claude mcp add 命令是注册MCP服务器的推荐方式——不要将它们添加到 ~/.claude/settings.json 因为该文件仅用于权限和挂钩。

可用工具

工具 说明
hello(name?) 说你好——占位符工具，用于验证服务器是否正常工作

用法示例

验证服务器是否正常工作：

hello()              → "Hello, World!"
hello(name="Alice")  → "Hello, Alice!"

添加自己的工具后，用2-3个现实的工作流程替换这些示例 展示了这些工具是如何组合在一起的。请参阅 gmail mcp服务器自述文件 一个好的模型。

发展

# Install dev dependencies
uv sync --dev

# Run tests
uv run pytest -v

# Run tests with coverage
uv run pytest --cov=mcp_server_template --cov-report=term-missing

# Lint
uv run ruff check src/ tests/

# Format
uv run ruff format src/ tests/

# Install git hooks
lefthook install

本地 .env 文件

在Claude Desktop/Code之外手动运行服务器时（例如，用于开发或 调试），您可以创建 .env 项目根目录中的文件，以便服务器拾取 不传递环境变量的config：

API_TOKEN=your_token_here

这只是当地发展所需要的。Claude桌面和Claude代码CLI配置 通过直接传递这些值 env 块。

发布

此项目使用 请释放 用于自动化 版本控制和发布。版本由以下因素决定 约定式提交:

  • fix: 提交bump 补丁 版本（例如0.1.0→ 0.1.1)
  • feat: 提交bump 次要的 版本（例如0.1.1→ 0.2.0)
  • BREAKING CHANGE 在提交页脚中颠簸 主要的 版本

当承诺土地 main，请打开（或更新）一个发布PR，该PR：

  • 将版本插入 pyproject.toml
  • 更新 CHANGELOG.md 带有分组条目

合并Release PR会自动创建一个git标签和GitHub Release。

启动一个新项目

使用 bootstrap.sh 要从此模板创建新的MCP服务器，请执行以下操作：

./bootstrap.sh my-service my_service_package your-github-user "Your Name"

这将重命名所有占位符（包名、徽章、许可证版权），更新配置，并让您准备好编码。

包装与配送

此服务器目前通过git作为源代码分发。要安装：

git clone https://github.com/stevesimpson418/mcp-repo-template.git
cd mcp-server-template
uv sync

这是目前本地stdio MCP服务器的标准分发模型。该项目是 已经配置为通过掀背车进行车轮制造，因此未来的分销选项包括：

  • PyPI --发布到PyPI，然后安装 uv tool install <your-package> 或 pip install <your-package>。需要向CI添加发布工作流。
  • uvx --一旦在PyPI上， uvx <your-package> 在不克隆仓库的情况下运行服务器。 Claude Desktop/Code配置将指向uvx管理的二进制文件，而不是本地文件 .venv.

许可证

麻省理工学院

相关 MCP