AI导哈

容器化模型上下文协议服务器

一个基于FastMCP框架和Docker的轻量级模型上下文协议服务器，提供安全隔离的执行环境和灵活的访问控制，适用于构建自定义MCP工具。

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

使用说明

MCP模板-Docker化模型上下文协议服务器

使用FastMCP和Docker构建的最小容器化模型上下文协议（MCP）服务器。这为构建具有安全、隔离执行环境的MCP服务器提供了一个干净的起点。

特性

  • 🐳 完全码头化 -无需在本地安装依赖项
  • 🔒 灵活的访问控制 -根据需要授予从只读到完全写访问的精确文件系统权限
  • 🚀 FastMCP框架 -基于装饰器的简单工具创建
  • 🔧 只是整合 -具有选项卡完成功能的现代构建自动化
  • 🧪 MCP检查员就绪 -使用基于浏览器的工具轻松测试
  • ⚡ 最小设置 -几秒钟后开始

快速开始

先决条件

  • 码头工人
  • Node.js （可选，适用于MCP检查员）
  • 就 （可选，用于构建自动化）

仅安装（推荐）

# macOS
brew install just

# Other platforms: see https://github.com/casey/just?tab=readme-ov-file#installation

用法

# Build the Docker image
just build

# Test with MCP Inspector (provides URL to open in browser)
just test

# Interactive development shell
just dev

# Run MCP server in background
just serve

手动使用（无Just）

# Build
docker build -t mcp-template .

# Test with Inspector
npx @modelcontextprotocol/inspector docker run -i --rm mcp-template

# Run in background
docker run -i -d --rm mcp-template

测试

MCP检查器提供了一个基于web的界面来测试您的工具：

  1. 跑 just test （或手动npx命令）
  2. 从终端输出中复制预填充的URL（包括身份验证令牌）
  3. 在浏览器中打开URL
  4. 单击“连接”连接到您的服务器
  5. “工具”选项卡中的测试工具

项目结构

mcp-template/
├── Dockerfile      # Container definition
├── server.py       # MCP server implementation
├── justfile        # Build automation
└── README.md       # This file

示例工具

服务器当前包括一个示例工具：

  • add(a, b) -将两个数字相加

扩展服务器

通过使用创建函数来添加新工具 @mcp.tool 装饰师：

@mcp.tool
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b

@mcp.tool
def multiply(a: int, b: int) -> int:
    """Multiply two numbers"""
    return a * b

安全和访问控制

此模板强调 安全、受控的访问 到您的文件系统。

受控文件访问

默认情况下，容器具有 无权限 到您的主机文件。您可以使用卷装载明确授予访问权限：

# Read-only access to specific directories
docker run -i --rm -v $HOME/my-docs:/workdir/docs:ro mcp-template
docker run -i --rm -v $HOME/code:/workdir/code:ro mcp-template

# Read-write access
docker run -i --rm -v $HOME/sandbox:/workdir/sandbox:rw mcp-template

最高安全配置

为了获得最安全的设置，请组合多个标志：

docker run -i --rm \
  --network none \
  --user $(id -u):$(id -g) \
  --read-only \
  --tmpfs /tmp \
  --cap-drop ALL \
  --security-opt no-new-privileges \
  -v $HOME/safe-folder:/workdir/data:ro \
  mcp-template

注意：您可能需要更换 $(id -u):$(id -g) 和 $HOME 代理配置上有明确的值。

安全标志详细信息

为了增强安全性，请考虑添加以下Docker标志：

• --network none -完全禁用网络访问

  • 阻止容器进行任何网络连接
  • 非常适合不需要互联网接入的文件处理工具
  • 例子： docker run -i --rm --network none mcp-template

• --user $(id -u):$(id -g) -以当前用户身份运行容器

  • 防止根权限升级
  • 由容器创建的文件将拥有您的用户所有权
  • 例子： docker run -i --rm --user $(id -u):$(id -g) mcp-template

• --read-only -使容器文件系统为只读

  • 防止容器修改自己的文件
  • 通过限制容器持久化更改的能力来增强安全性
  • 例子： docker run -i --rm --read-only mcp-template

• --tmpfs /tmp -在内存中提供临时文件系统

  • 允许容器写入/tmp而不影响主机
  • 与结合使用时有用 --read-only
  • 例子： docker run -i --rm --read-only --tmpfs /tmp mcp-template

• --cap-drop ALL -删除所有Linux功能

  • 最小化容器权限
  • 防止容器执行特权操作
  • 例子： docker run -i --rm --cap-drop ALL mcp-template

• --security-opt no-new-privileges -防止特权升级

  • 阻止进程获得额外权限
  • 增加了针对潜在漏洞的安全层
  • 例子： docker run -i --rm --security-opt no-new-privileges mcp-template

为什么这很重要

  • 防止事故发生 -除非明确允许，否则MCP服务器无法修改文件
  • 限制范围 -仅装载服务器实际需要的目录
  • 审核访问权限 -清楚地了解哪些目录是可访问的
  • 安全实验 -在实际数据上使用之前，在副本/沙盒上测试工具
  • 纵深防御 -多个安全层可抵御各种攻击媒介

这种方法允许您在维护的同时构建强大的MCP工具 细粒度控制 关于他们可以访问的内容。

配置

连接到克劳德桌面

要将此MCP服务器与Claude Desktop一起使用，请将其添加到您的 claude_desktop_config.json 配置文件：

基本配置：

{
  "mcpServers": {
    "mcp-template": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "mcp-template"
      ]
    }
  }
}

具有文档读取权限的配置：

{
  "mcpServers": {
    "mcp-template": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "<REPLACE_WITH_HOME_PATH>/Documents:/workdir/docs:ro",
        "mcp-template"
      ]
    }
  }
}

最高安全配置（无网络，最低权限）：

{
  "mcpServers": {
    "mcp-template-max-secure": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--network", "none",
        "--user", "<REPLACE_WITH_USER>:<REPLACE_WITH_GROUP>",
        "--read-only",
        "--tmpfs", "/tmp",
        "--cap-drop", "ALL",
        "--security-opt", "no-new-privileges",
        "-v", "<REPLACE_WITH_HOME_PATH>/Documents:/workdir/docs:ro",
        "mcp-template"
      ]
    }
  }
}

添加此配置后，重新启动Claude Desktop。MCP服务器将显示为克劳德在对话中可以使用的可用工具。

自动发布（可选）

此模板包含GitHub操作(.github/workflows/docker-publish.yml)自动将Docker镜像发布到 Docker Hub 当你推送代码时。

要使用Docker Hub发布：

  1. 创建Docker Hub帐户和存储库
  2. 将这些添加到您的GitHub存储库设置中：
    • 变量: DOCKERHUB_USERNAME （您的Docker Hub用户名）
    • 秘密: DOCKERHUB_TOKEN （您的Docker Hub访问令牌）
  3. 推到 main 分支或创建任何标签→ 自动构建和发布Docker镜像

要删除自动发布，请执行以下操作：

如果你不想自动发布Docker Hub，只需删除：

rm .github/workflows/docker-publish.yml

开发工作流程

  1. 编辑 server.py 用你的工具
  2. 构建 随着 just build
  3. 测试 随着 just test
  4. 迭代 重复

故障排除

检查器中的“连接错误”

  • 确保您使用的是终端输出中提供的身份验证令牌URL
  • 检查容器是否成功启动（docker ps）

集装箱立即退出（检查日志）

docker ps
docker logs <name>

工具未出现

  • 验证 @mcp.tool 装饰师在场
  • 检查函数是否有docstring
  • 更改后重建容器

许可证

MIT许可证-您可以将其作为您自己的MCP服务器的起点。

资源

相关 MCP