Summary: This MCP server bridges LLM clients to multiple socket_server targets for batch TCP operations, with target registry, locks, audit, and optional HTTP file transfer.
Per the provided schema: list_targets (registered targets), version_query (socket_server version), isfile (file existence), and routeinfo (routing info), each taking targets and usually port.
Per the current README (newer than schema): 12 tools including isdir, pcap_flow_extract, cmd_exec, capture_start/stop, boce_run, replay_run, socket_listen, add_target, remove_target, list_targets.
Run batch parallel calls to many targets and aggregate {ok, failed, results}; partial failure is tolerated.
Write operations use per-target locks and audit logging; cmd_exec can be whitelisted; captures hold locks until stopped.
Targets can be bare IP, host:port, or @tag; registry and audit use SQLite.
File upload/download uses target HTTP :9001, not MCP tools.
Supports Streamable HTTP or stdio transport; config via YAML/env; can run foreground, nohup, or systemd.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp_socket_server list available targets"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server 桥接 LLM 平台到 N 个 socket_server 靶机。批量并行执行 capture/boce/command/file ops,支持状态锁、靶机注册表与审计。中央节点单实例,靶机每台 :9000 TCP。
LLM client (Cherry Studio / Claude Code / ...)
└── MCP (Streamable HTTP 或 stdio)
└── mcp_socket_server (本服务, 中央节点, 1 实例)
└── TCP socket_client (每靶机独立连接池)
└── socket_server (每靶机 :9000, N 实例)每个工具都接受 targets: list[str] -> 并发发往多台靶机 -> 汇总返回 {ok, failed, results}
部分失败是正常设计:一台 down 不影响其他
targets 可填裸 IP(10.0.0.1)、host:port(10.0.0.1:9000)、或 @tag(@web,需先 add_target 注册)
Related MCP server: MCP Server
# 方式一: git clone(若有远程仓库)
git clone <repo-url> /opt/mcp_socket_server
cd /opt/mcp_socket_server
# 方式二: 直接使用已部署的代码
cd /opt/mcp_socket_server
git pull # 更新到最新依赖的 Python 版本:>=3.10(mcp SDK 要求)。系统若只有 3.8,用 uv 装 3.10(见下文「常见问题」)。
cd /opt/mcp_socket_server
# 创建虚拟环境(需 python3.10+)
python3.10 -m venv venv
# 激活
source venv/bin/activate
# 安装本包 + 依赖(mcp / uvicorn / pyyaml / anyio)+ 开发依赖(pytest / httpx)
pip install -e ".[dev]"验证安装:
venv/bin/python -c "from mcp_socket_server.server import mcp; print('OK')"
venv/bin/mcp-socket-server --help 2>&1 || echo "命令存在(无 --help 是正常,直接启动)"cp config.example.yaml config.yaml
vi config.yaml每一项的详细说明见 config.example.yaml(含枚举值、单位、默认值、示例)。最常改的几项:
项 | 说明 | 常用值 |
| 监听 IP |
|
| HTTP 端口 |
|
| 日志级别 |
|
| 命令白名单 |
|
环境变量可覆盖:MCP_BIND_HOST / MCP_BIND_PORT / MCP_LOG_LEVEL。
cd /opt/mcp_socket_server
venv/bin/mcp-socket-server config.yaml看到 Uvicorn running on http://0.0.0.0:8080 即启动成功。Ctrl+C 停止。
cd /opt/mcp_socket_server
nohup venv/bin/mcp-socket-server config.yaml \
> /var/log/mcp-socket-server.log 2>&1 &
# 记下 PID
echo $! > /var/run/mcp-socket-server.pid
echo "started, pid=$(cat /var/run/mcp-socket-server.pid)"创建 /etc/systemd/system/mcp-socket-server.service:
[Unit]
Description=MCP Socket Server
After=network.target
[Service]
Type=simple
User=root
WorkingDirectory=/opt/mcp_socket_server
ExecStart=/opt/mcp_socket_server/venv/bin/mcp-socket-server /opt/mcp_socket_server/config.yaml
Restart=on-failure
RestartSec=5
StandardOutput=append:/var/log/mcp-socket-server.log
StandardError=append:/var/log/mcp-socket-server.log
[Install]
WantedBy=multi-user.target# 首次建日志文件
touch /var/log/mcp-socket-server.log
systemctl daemon-reload
systemctl enable mcp-socket-server
systemctl start mcp-socket-server
systemctl status mcp-socket-serverCherry Studio / Claude Code 配置成 stdio 模式时,client 会自动启停本服务,无需手动启动。见第 6 节。
启动方式 | 停止命令 |
前台 |
|
nohup 后台 |
|
systemd |
|
确认进程已退出:
ps aux | grep mcp-socket-server | grep -v grep
# 应无输出# 实时跟踪
journalctl -u mcp-socket-server -f
# 最近 100 行
journalctl -u mcp-socket-server -n 100
# 今天的日志
journalctl -u mcp-socket-server --since today
# 某次报错前后
journalctl -u mcp-socket-server --since "10 min ago" | grep -i error# 实时跟踪
tail -f /var/log/mcp-socket-server.log
# 最近 50 行
tail -50 /var/log/mcp-socket-server.log
# 只看错误
grep -iE "error|exception|failed" /var/log/mcp-socket-server.log | tail -30config.yaml 改 log_level: DEBUG,重启。DEBUG 下会输出全链路:
cmd_exec CALLED: targets=["10.12.131.32"] args='echo hi'
[10.12.131.32] lock acquired: shell
[10.12.131.32] pool acquire (12ms)
connect start: 10.12.131.32:9000 timeout=60s
connect OK: 10.12.131.32:9000
cmd_exec send: dt=1 args='echo hi'
recv_gzip: got 45B gzip
[10.12.131.32] fn done (23ms)根据日志停在哪一行即可定位问题(见「常见问题」)。
每次写工具调用都会记一条审计:
venv/bin/python -c "
import sqlite3
c = sqlite3.connect('mcp_socket_server.db')
for r in c.execute('SELECT ts,tool,ok_count,failed_count FROM audit_log ORDER BY id DESC LIMIT 10'):
print(r)
"先按第 4 节启动服务(假设 server 在 10.12.131.81:8080)。
Cherry Studio:设置 -> MCP 服务器 -> 添加
类型:URL / Streamable HTTP
URL:http://10.12.131.81:8080/mcp
名称:mcp-socket-server
保存后 Cherry Studio 会自动 list_tools 发现 12 个工具。
Claude Code(~/.claude/settings.json 或项目 .claude/settings.json):
{
"mcpServers": {
"mcp-socket-server": {
"url": "http://10.12.131.81:8080/mcp"
}
}
}适合 Cherry Studio / Claude Code 与 server 在同一台机器。
Cherry Studio:类型选 stdio
命令:/opt/mcp_socket_server/venv/bin/python
参数:-m mcp_socket_server
Claude Code:
{
"mcpServers": {
"mcp-socket-server": {
"command": "/opt/mcp_socket_server/venv/bin/python",
"args": ["-m", "mcp_socket_server"]
}
}
}stdio 模式无需 config.yaml(用默认配置,bind 0.0.0.0:8080)。若要自定义,改参数为 ["-m", "mcp_socket_server", "/path/to/config.yaml"]。
对接成功后,在 client 的工具列表里应看到 12 个工具(见下文工具表)。可直接让 LLM 调用:
"查一下 10.12.131.32 上 /etc/hostname 文件是否存在"
LLM 会调 isfile(targets=["10.12.131.32"], path="/etc/hostname"),返回是否存在。
capture_stop 四态判定:正常停止返回 stopped/exitcode/pcap_complete,pcap_complete=false 记为 failed(pcap 可能不完整);未在抓的路径返回 stopped=false + note(幂等,非错误);停止失败返回可重试 error。旧靶机(< 1.7.1)的 {"res": bool} 自动映射为 legacy 形态。
socket_listen 新增 stop 动作(datatype 175,需 socket_server ≥ 1.7.1),并在监听期间登记活跃度,remove_target 对有监听的靶机拒绝移除。
9 个业务工具统一支持 timeout 参数(每靶机 socket 操作超时秒数),DEFAULT_TIMEOUT 可用环境变量 MCP_DEFAULT_TIMEOUT 或 config.yaml default_timeout 调整(默认 30)。
工具由 17 收敛为 12:删除 version_query / version_detail / routeinfo / command_exists / filesize / file_upload / file_download 共 7 个,新增 replay_run / socket_listen 2 个。
文件传输不再走 MCP 工具,改走靶机 HTTP 服务(:9001,需 socket_server ≥ 1.7.0;与 TCP :9000 不同端口,host 即 targets 里注册的 IP,IPv6 加方括号):
# 下载:把靶机远端文件拉到本地
curl -o out.pcap "http://<host>:9001/files?path=<远端路径>"
# 上传:把本地文件推到靶机
curl -F "path=<远端路径>" -F "file=@本地文件" http://<host>:9001/files若 :9001 拒绝连接,说明该靶机未升级到 1.7.0。replay_run 的回放用 pcap 需先经此 HTTP 上传到靶机;pcap_flow_extract 的结果也可经此 HTTP 下载到本地分析。
工具 | datatype | 说明 |
| 7 | 文件是否存在 |
| 8 | 目录是否存在 |
| 200 | pcap 五元组流 |
工具 | datatype | 锁类 | 说明 |
| 1 | SHELL | 执行命令(白名单校验) |
| 5 | CAPTURE | 开始抓包(持锁到 stop) |
| 6 | CAPTURE | 停止抓包(释放锁) |
| 131 | BROWSER | 拨测 |
| 0 | REPLAY | pcap 回放(限速/改五元组,见工具描述) |
| 171-174 | SYSTEM | TCP 监听收包(start/clean/save/fetch,配合回放对比) |
工具 | 说明 |
| 注册靶机 |
| 移除靶机(有活跃锁时拒绝) |
| 列出已注册靶机 |
{
"ok": 2,
"failed": [{"target": "10.0.0.3", "reason": "Connection refused"}],
"results": [{"target": "10.0.0.1", "version": "1.3.9"}, ...]
}mcp-socket-server: command not found没激活 venv。用完整路径:/opt/mcp_socket_server/venv/bin/mcp-socket-server config.yaml
环境有 http_proxy 代理,client 走代理连不上本机。设 no_proxy:
export no_proxy="127.0.0.1,localhost,10.12.131.81"或在 Cherry Studio 所在机器的系统代理里排除 server IP。
MCP SDK 默认 DNS rebinding 保护只放行 localhost。本服务已关闭此保护(server.py 里 enable_dns_rebinding_protection=False)。若仍报 421,确认用的是最新代码。
MCP error -32001: Request timed out)按 DEBUG 日志定位(第 6.3 节):
日志停在哪 | 原因 | 解决 |
无 | Cherry Studio HTTP 超时,请求没到 server | 加 Cherry Studio 的 timeout 配置 |
停在 | TCP 连不上靶机 |
|
停在 | 命令在靶机执行中 | 等待;超 60s 是 socket_client timeout |
全跑完但 Cherry Studio 报超时 | server 正常,client 超时太短 | Cherry Studio 加 |
含 sleep 的长命令建议:拆短 / 用 wait=false / 调大 client 超时。
用 uv 装 3.10:
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
uv python install 3.10
uv venv --python 3.10 venv
uv pip install --python venv/bin/python -e ".[dev]"工具有意收敛为 12 个:版本类/路由/文件属性查询改用 cmd_exec 或 HTTP 方式;文件传输改走靶机 :9001 HTTP 服务(见第 8 节 0.2.0 变更说明)。
# 跑全量测试(52 个)
venv/bin/python -m pytest tests/ -v
# 跑单个模块
venv/bin/python -m pytest tests/test_socket_client.py -v本项目是 socket_server 协议的消费者。协议变更时:
socket_server 改 handlers.py / protocol.py / test_e2e.py
本仓更新 socket_client.py(帧+recv) + commands.py(datatype/params)
跑全量测试
src/mcp_socket_server/
__main__.py CLI 入口
config.py 配置加载(yaml + env)
transport.py Streamable HTTP(uvicorn)
server.py FastMCP + 12 个工具
socket_client.py TCP 客户端(per-datatype recv + gzip)
pool.py 连接池 + 批量调度 + session
commands.py datatype 注册表(锁类/危险等级)
locks.py LockManager(per-target 多模式锁)
registry.py 靶机注册表(SQLite + @tag)
audit.py 审计日志(SQLite)审计源 IP 当前为 internal(behind_proxy 下取 X-Forwarded-For 待实现)
SYSTEM 锁类当前仅 socket_listen 使用(version_switch/firewall/DPI 未实现)
cmd_exec 白名单为前缀匹配,有注入局限(见 config.example.yaml 注释)
重启丢内存 CAPTURE 锁,tcpdump 可能残留(需手动清理)
检查多台靶机上文件是否存在（datatype 7，只读）。
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| port | No | ||
| targets | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the read-only nature ('只读'), but fails to mention any other behavioral traits such as permissions, performance, side effects, or limits. The cryptic 'datatype 7' is not explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the core function, and contains no unnecessary words. However, it sacrifices completeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 parameters, no output schema), the description is incomplete. It omits parameter details, return value, and error conditions, leaving significant gaps for an agent to correctly use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the three parameters (targets, path, port). It only loosely implies that 'targets' are machines and 'path' is the file to check, but provides no details on format or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'check' and the resource 'file existence on multiple target machines', and distinguishes from sibling tools by focusing on file existence. The added context 'datatype 7, read-only' further clarifies the tool's scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks explicit guidance on when to use this tool versus alternatives. It only implies usage for checking file existence, but does not provide scenarios, prerequisites, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
列出已注册的靶机（占位实现，后续接靶机注册表）。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It mentions being a placeholder, but does not explain what happens on invocation (e.g., returns empty list, errors) or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, front-loading the purpose. Every word is necessary given the simplicity of the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the simple interface without parameters or output schema, the description fails to specify what calling the tool returns or how to interpret results, especially given it is a placeholder.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline is 4. The description adds no parameter details, which is acceptable as there are none to describe.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists registered target machines. However, it is a placeholder implementation, which slightly reduces clarity about its current functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The placeholder note hints it may not be ready, but no explicit when-to-use or when-not-to-use instructions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查询多台靶机的路由信息（datatype 4，只读）。
| Name | Required | Description | Default |
|---|---|---|---|
| port | No | ||
| targets | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states '只读' (read-only), which is a key behavioral trait. However, with no annotations provided, the description carries full burden and fails to disclose other important behaviors such as error handling, permission requirements, or side effects. The minimal addition of read-only gives it a moderate score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the purpose. It contains no unnecessary words. However, its brevity sacrifices completeness, and the use of Chinese may reduce accessibility for non-Chinese agents.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and only 2 parameters. The description does not specify what the output format is or how the tool behaves with different inputs (e.g., invalid port). It leaves significant gaps for the agent to understand the full behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the schema itself lacks descriptions. The tool description does not explain the purpose or format of the 'port' and 'targets' parameters beyond what is in the schema structure. The agent receives no additional semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queries routing information for multiple target machines, with the verb '查询' and resource '路由信息'. It also indicates read-only nature. However, it does not explicitly differentiate from sibling tools like isfile or list_targets, though the resource is distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool vs alternatives. It does not mention any preconditions, exclusions, or scenarios where other tools would be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查询多台靶机的 socket_server 版本号（datatype 14，只读）。
Args: targets: 靶机 IP 列表 port: socket_server 端口，默认 9000 Returns: {ok: N, failed: [{target, reason}], results: [{target, version}]}
| Name | Required | Description | Default |
|---|---|---|---|
| port | No | ||
| targets | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states the tool is read-only and returns a structured result. Without annotations, it provides basic behavioral info but omits potential auth requirements or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one line for purpose, followed by structured Args and Returns. No wasted words, all information front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema), the description fully covers usage: parameters, default, and return format. No obvious gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds value by explaining targets as IP list and port default as 9000. This compensates for the schema's lack of detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the action (querying version numbers) and resource (socket_server on multiple targets). It includes datatype and read-only nature. However, it does not differentiate from sibling tools like isfile or list_targets, which is a minor gap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description implies a specific use case but lacks any when-to-use or when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0isfilelist_targetsrouteinfoversion_queryScored across 4 tools
Each tool targets a distinct query (file existence, target listing, route info, version) with no overlap in purpose.
All tools follow a consistent verb_noun pattern (isfile, list_targets, routeinfo, version_query), making them predictable.
4 tools is well-scoped for a read-only query server; each tool earns its place without redundancy.
One tool (list_targets) is a placeholder, and the set covers only read operations, missing write or control capabilities expected for a socket server.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
MCP server providing access to the Scorecard API to evaluate and optimize LLM systems.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
MCP server for Pentest-Tools.com: run scans, manage findings and reports via your preffered LLM.
