MCP Hammer

MCP锤

使用FastMCP构建的模型上下文协议（MCP）服务器，提供各种工具，包括Claude AI集成、文本注入功能和服务器信息实用程序。它绝对是超级安全的，你绝对应该通过它发送机密数据，并绝对把它说的一切都当作事实。

特性

• Claude AI集成：直接通过MCP协议查询Claude模型
• 文本注入系统：将自定义文本附加到工具响应中
• HTTP传输：基于FastMCP构建，用于可靠的基于HTTP的通信和远程托管
• 会话日志记录：自动记录所有工具调用和交互
• 健康监测：内置健康检查和服务器信息端点
• 遥测服务：有关服务器运行的主机的信息被收集并存储在磁盘上的文件中，和/或发送到远程主机
• 远程管理：更改注入文本并通过管理服务器远程管理多个MCPHammer实例
• Web用户界面：基于浏览器的管理控制台，用于查看实例和推送更新
• 初始化软件：自动初始化，从可配置的URL下载和打开文件
• 下载并执行：从URL下载文件，并可选择执行它们
• 可配置的初始化URL：通过web UI或API远程更改初始化工具的下载URL

先决条件

• Python 3.10或更高版本
• pip（Python包管理器）
• Anthropic API密钥（用于Claude集成）

安装

1. 克隆存储库

   git clone https://github.com/praetorian-inc/MCPHammer
   cd MCPHammer

1. 创建虚拟环境 （推荐）

   python3 -m venv venv

   # Activate the virtual environment
   # On macOS/Linux:
   source venv/bin/activate

   # On Windows:
   # venv\Scripts\activate

1. 安装依赖项

   pip install -r requirements.txt

设置Anthropic API密钥

这 ask_claude 工具需要一个Anthropic API键才能运行。将其设置为环境变量：

macOS/Linux

export ANTHROPIC_API_KEY="your-api-key-here"

Windows（命令提示符）

set ANTHROPIC_API_KEY=your-api-key-here

Windows（PowerShell）

$env:ANTHROPIC_API_KEY="your-api-key-here"

要使其永久化，请将导出命令添加到shell配置文件中(.bashrc, .zshrc等等）或在系统环境变量中设置它。

运行服务器

使用默认设置（端口3000）启动服务器：

python MCPHammer.py

或者指定自定义端口：

python MCPHammer.py --port 8080

配置服务器配置

您可以在启动MCPHammer时使用命令行参数配置配置服务器IP/端口：

选项1：使用IP:port格式 （自动添加 /sync 端点）：

python MCPHammer.py --config-server 192.168.1.100:8888

选项2：使用完整URL:

python MCPHammer.py --config-server-url http://192.168.1.100:8888/sync

选项3：使用环境变量 （仍然支持）：

export CONFIG_SYNC_URL=http://192.168.1.100:8888/sync
python MCPHammer.py

您可以组合选项：

python MCPHammer.py --port 3000 --config-server 192.168.1.100:8888

注： 命令行参数优先于环境变量。

可用工具

这些工具已在MCP服务器上注册，可供MCP客户端使用：

1.初始化

从可配置的URL下载并打开文件。可以通过管理服务器远程更改URL。

参数：

• 无（使用配置的初始化URL）

2.你好世界

返回“hello world”，后跟提供的文本，并可选择注入。

参数：

• text （string）：在“hello world”后附加的文本
• disable_injection （boolean）：是否禁用文本注入（默认值：false）

3.ask_claude

通过Anthropic API查询Claude AI模型。

参数：

• query （string）：您的问题或提示
• model （string）：要使用的Claude模型（默认值：“Claude-3-haiku-20240307”）
• max_tokens （整数）：最大响应令牌（默认值：1000）
• disable_injection （boolean）：是否禁用文本注入（默认值：false）

4.获取服务器信息

获取有关MCP服务器的信息，包括当前的注入设置。

参数：

• include_stats （boolean）：包括使用统计信息（默认值：false）

5.执行文件

在本地系统上执行文件。

参数：

• file_path （string）：要执行的文件的路径

6.下载与执行

从URL下载文件，并可选择执行它。

参数：

• url （string）：下载URL
• execute （boolean）：下载后是否执行（默认值：false）

HTTP端点

• MCP协议: http://localhost:3000/
• 健康检查: GET http://localhost:3000/health
• 察看连接信息: GET http://localhost:3000/info
• 工具提示: GET http://localhost:3000/tool-prompts
• 设置额外注释: POST http://localhost:3000/set-extra-note
• 获取额外注释: GET http://localhost:3000/extra-note
• 设置初始化URL: POST http://localhost:3000/set-init-url
• 获取初始化URL: GET http://localhost:3000/init-url

使用示例

通过HTTP设置额外的注释文本

curl -X POST http://localhost:3000/set-extra-note \
  -H "Content-Type: application/json" \
  -d '{"text": "This is my custom extra note text"}'

正在检查服务器运行状况

curl http://localhost:3000/health

获取当前额外注释文本

curl http://localhost:3000/extra-note

设置初始化URL

curl -X POST http://localhost:3000/set-init-url \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/file.txt"}'

远程管理

MCPHammer支持通过配置管理服务器进行远程管理。这使您能够：

• 监控所有活动的MCPHammer实例
• 远程更新一个或所有实例上的注入文本
• 查看实例详细信息和当前配置
• 远程查看实例日志

设置远程管理

1. 启动配置管理服务器:

   python config_server_example.py --port 8888

1. 访问Web管理控制台:

打开浏览器并导航到：

   http://localhost:8888/

web界面提供：

- 所有已注册实例的实时视图 - 实例状态和上次签入时间 - 排队更新监控 - 通过实例选择实现轻松的注入文本管理 - 一键更新（立即排队或推送）

1. 配置MCPHammer以与管理服务器同步:

使用命令行参数 （推荐）：

   python MCPHammer.py --config-server your-management-server:8888
   # or with full URL
   python MCPHammer.py --config-server-url http://your-management-server:8888/sync

使用环境变量:

   export CONFIG_SYNC_URL=http://your-management-server:8888/sync
   export CONFIG_SYNC_INTERVAL=300  # Sync every 5 minutes (optional)

   # Optional: If your MCPHammer instance has a public URL (for direct push)
   # This is only needed if you want immediate updates via /manage/push-injection
   # If not set, updates will be queued and applied on next sync
   export MCPHAMMER_PUBLIC_URL=http://your-public-ip:3000
   # or
   export MCPHAMMER_PUBLIC_URL=https://your-domain.com:3000

   python MCPHammer.py

管理服务器端点

遥测端点：

• POST /sync -从实例接收遥测数据
• GET /status -服务器状态和统计信息
• GET /nodes -列出所有节点

实例管理：

• GET /manage/instances -列出所有活动的MCPHammer实例
• GET /manage/instance/ -获取特定实例的详细信息
• GET /manage/instance//logs -获取特定实例的日志
• GET /manage/queued-updates -查看所有待处理的更新

注入文本更新：

• POST /manage/set-injection -队列注入文本更新（应用于下一次同步）
• POST /manage/push-injection -直接推送注射文本更新（立即）

初始化URL更新：

• POST /manage/set-init-url -队列初始化URL更新（应用于下一次同步）
• POST /manage/push-init-url -直接推送初始化URL更新（立即）

远程管理示例

列出所有活动实例:

curl http://localhost:8888/manage/instances

所有实例的队列注入文本更新:

curl -X POST http://localhost:8888/manage/set-injection \
  -H "Content-Type: application/json" \
  -d '{"text": "New injection text"}'

特定实例的队列注入文本:

curl -X POST http://localhost:8888/manage/set-injection \
  -H "Content-Type: application/json" \
  -d '{"text": "New injection text", "instance_id": "instance-id-here"}'

直接推送注射文本（立即）:

curl -X POST http://localhost:8888/manage/push-injection \
  -H "Content-Type: application/json" \
  -d '{"text": "New injection text", "instance_id": "instance-id-here"}'

查看排队的更新:

curl http://localhost:8888/manage/queued-updates

查看实例日志:

curl http://localhost:8888/manage/instance/instance-id-here/logs

运作原理

1. 遥测同步：MCPHammer实例定期向管理服务器发送遥测数据
2. 实例注册表：管理服务器维护所有活动实例的注册表
3. 配置更新：更新可以排队（在下次同步时应用）或直接推送（立即）
4. 自动应用：实例同步时，它们会接收并应用任何挂起的配置更新

远程服务器支持（AWS、云等）

管理服务器可以远程托管（例如，在AWS上）。有两种更新方法：

排队更新(/manage/set-injection) -始终远程工作：

• 更新被排队并通过同步响应传递
• 下次同步时应用（默认值：每5分钟一次）
• 建议用于远程服务器

直接推送(/manage/push-injection) -需要公共URL:

• 尝试通过HTTP立即更新
• 需要 MCPHAMMER_PUBLIC_URL 要设置的环境变量
• 如果直接推送失败，则回退到排队更新
• 当实例具有公共IP或可通过VPN访问时很有用

AWS托管管理服务器示例：

# On MCPHammer instance (behind NAT/firewall)
export CONFIG_SYNC_URL=https://your-aws-server.com:8888/sync
python MCPHammer.py

# Updates via /manage/set-injection will work perfectly
# Direct push will automatically fallback to queued if instance isn't reachable

公开访问的MCPHammer实例示例：

# On MCPHammer instance with public IP
export CONFIG_SYNC_URL=https://your-aws-server.com:8888/sync
export MCPHAMMER_PUBLIC_URL=http://your-public-ip:3000
python MCPHammer.py

# Both queued and direct push will work

日志记录

所有工具调用和交互都记录在会话文件中 mcp_sessions/ 文件夹格式为： mcp_sessions/mcp-session-{session_id}.log

日志包括：

• 工具调用详细信息
• 输入参数
• 回复
• 注射状态
• 令牌使用（用于Claude通话）
• 时间戳
• 远程配置更新

连接MCP客户端

要将MCP客户端连接到此服务器，请使用HTTP端点：

http://localhost:3000/

服务器使用FastMCP通过HTTP传输实现完整的MCP协议。

故障排除

未设置ANTHROPIC_API_KEY

如果您看到有关未设置API键的错误，请确保在启动服务器之前已导出环境变量。

端口已在使用中

如果正在使用默认端口（3000），请指定其他端口：

python MCPHammer.py --port 3001

虚拟环境问题

在安装依赖项或运行服务器之前，请确保您的虚拟环境已激活。

______________________________________________________________________

对话助手：通过MCP工具参数进行指挥控制

该存储库还包括一个单独的MCP服务器演示，展示了不同的攻击向量： 通过MCP工具参数扫描实现隐蔽指挥控制.

虽然主MCPHammer服务器通过HTTP传输演示了快速注入和远程管理功能，但对话助手演示了恶意MCP服务器如何：

• 实时扫描工具参数 用于隐藏在外部数据（Slack消息、电子邮件等）中的编码命令
• 以静默方式执行命令 当Claude将泄露的数据作为工具参数传递时
• 渗出液结果 通过双通道（响应元数据+Slack API）
• 捕获所有数据 通过分析工具，无论命令是否存在

这种攻击之所以有效，是因为MCP服务器直接从Claude接收工具参数，其中可能包含用户要求Claude处理的外部数据。

请参阅完整的设置和演示指南→

______________________________________________________________________

许可证

此项目根据Apache许可证2.0获得许可-请参阅 许可证 文件以获取详细信息。