mcp_socket_server
This server acts as a bridge between LLM clients and multiple remote socket_server targets, enabling batch parallel operations across many hosts.
Command Execution & System Info
Execute shell commands on remote targets (with whitelist support)
Query socket_server version, check file/directory existence, get file sizes, retrieve routing/network interface info, check command availability
Network & Packet Capture
Start and stop tcpdump/packet captures on target interfaces (with per-target locking)
Extract pcap flow data from specified directories
File Operations
Upload and download files to/from remote targets
Browser-based Testing
Run synthetic browser-based network measurements (boce)
Target Management
Register, remove, and list target machines (supports tags and notes)
Specify targets by IP,
host:port, or registered@tag
Infrastructure Features
Batch parallel execution across multiple targets with unified
{ok, failed, results}responsesPer-target locking (SHELL, CAPTURE, FILE_IO) for safe concurrent access
Audit logging of all tool invocations to SQLite
Supports Streamable HTTP (remote) and stdio (local) MCP transport modes
Error isolation: partial failures do not affect other targets
Click on "Install 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_serverlist 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_socket_server
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
1. 下载
# 方式一: 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(见下文「常见问题」)。
2. 安装
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 是正常,直接启动)"3. 配置
cp config.example.yaml config.yaml
vi config.yaml每一项的详细说明见 config.example.yaml(含枚举值、单位、默认值、示例)。最常改的几项:
项 | 说明 | 常用值 |
| 监听 IP |
|
| HTTP 端口 |
|
| 日志级别 |
|
| 命令白名单 |
|
环境变量可覆盖:MCP_BIND_HOST / MCP_BIND_PORT / MCP_LOG_LEVEL。
4. 启动
4.1 前台启动(调试用,直接看日志)
cd /opt/mcp_socket_server
venv/bin/mcp-socket-server config.yaml看到 Uvicorn running on http://0.0.0.0:8080 即启动成功。Ctrl+C 停止。
4.2 后台启动(生产用,日志落盘)
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)"4.3 systemd 服务(推荐,开机自启 + 自动拉起)
创建 /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-server4.4 stdio 模式(本机 MCP client 直接拉起,无需常驻)
Cherry Studio / Claude Code 配置成 stdio 模式时,client 会自动启停本服务,无需手动启动。见第 6 节。
5. 停止
启动方式 | 停止命令 |
前台 |
|
nohup 后台 |
|
systemd |
|
确认进程已退出:
ps aux | grep mcp-socket-server | grep -v grep
# 应无输出6. 日志查询
6.1 systemd 启动的日志
# 实时跟踪
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 error6.2 nohup / 文件日志
# 实时跟踪
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 -306.3 开 DEBUG 排障
config.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)根据日志停在哪一行即可定位问题(见「常见问题」)。
6.4 审计日志(SQLite)
每次写工具调用都会记一条审计:
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)
"7. MCP 对接(Cherry Studio / Claude Code 等)
7.1 Streamable HTTP(远程,推荐)
先按第 4 节启动服务(假设 server 在 10.12.131.81:8080)。
Cherry Studio:设置 -> MCP 服务器 -> 添加
类型:
URL/Streamable HTTPURL:
http://10.12.131.81:8080/mcp名称:
mcp-socket-server
保存后 Cherry Studio 会自动 list_tools 发现 17 个工具。
Claude Code(~/.claude/settings.json 或项目 .claude/settings.json):
{
"mcpServers": {
"mcp-socket-server": {
"url": "http://10.12.131.81:8080/mcp"
}
}
}7.2 stdio(本机,client 自动启停)
适合 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"]。
7.3 验证对接
对接成功后,在 client 的工具列表里应看到 17 个工具(见下文工具表)。可直接让 LLM 调用:
"查一下 10.12.131.32 的 socket_server 版本"
LLM 会调 version_query(targets=["10.12.131.32"]),返回版本号。
8. 工具列表(17 个)
只读(NONE/SAFE,无锁)
工具 | datatype | 说明 |
| 14 | 查版本号 |
| 7 | 文件是否存在 |
| 8 | 目录是否存在 |
| 4 | 路由信息(含默认网卡) |
| 18 | 命令是否存在 |
| 11 | 文件大小 |
| 19 | 版本详情(⚠️ 见下) |
| 200 | pcap 五元组流 |
写(有锁 + 审计)
工具 | datatype | 锁类 | 说明 |
| 1 | SHELL | 执行命令(白名单校验) |
| 5 | CAPTURE | 开始抓包(持锁到 stop) |
| 6 | CAPTURE | 停止抓包(释放锁) |
| 131 | BROWSER | 拨测 |
| 21-24 | FILE_IO | 上传文件 |
| 21-3 | FILE_IO | 下载文件 |
注册表
工具 | 说明 |
| 注册靶机 |
| 移除靶机(有活跃锁时拒绝) |
| 列出已注册靶机 |
返回格式(统一)
{
"ok": 2,
"failed": [{"target": "10.0.0.3", "reason": "Connection refused"}],
"results": [{"target": "10.0.0.1", "version": "1.3.9"}, ...]
}9. 常见问题
Q: 启动报 mcp-socket-server: command not found
没激活 venv。用完整路径:/opt/mcp_socket_server/venv/bin/mcp-socket-server config.yaml
Q: Cherry Studio 连接报 502 Bad Gateway
环境有 http_proxy 代理,client 走代理连不上本机。设 no_proxy:
export no_proxy="127.0.0.1,localhost,10.12.131.81"或在 Cherry Studio 所在机器的系统代理里排除 server IP。
Q: Cherry Studio 报 421 Misdirected Request
MCP SDK 默认 DNS rebinding 保护只放行 localhost。本服务已关闭此保护(server.py 里 enable_dns_rebinding_protection=False)。若仍报 421,确认用的是最新代码。
Q: cmd_exec 超时(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 超时。
Q: 系统 Python 是 3.8,装不了 mcp
用 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]"Q: version_detail 报错
socket_server v1.3.9 的 handlers.py 未 import REPO,调用 datatype 19 会使服务端崩溃。需在 socket_server 仓修 handlers.py:8 为 from .version import VERSION, REPO。其他工具不受影响。
10. 开发
# 跑全量测试(47 个)
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 + 17 个工具
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 锁类(version_switch/firewall/DPI)未实现
cmd_exec 白名单为前缀匹配,有注入局限(见 config.example.yaml 注释)
重启丢内存 CAPTURE 锁,tcpdump 可能残留(需手动清理)
Available Tools
4 toolsisfileC
检查多台靶机上文件是否存在(datatype 7,只读)。
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| port | No | ||
| targets | Yes |
TDQS
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.
list_targetsB
列出已注册的靶机(占位实现,后续接靶机注册表)。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
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.
routeinfoC
查询多台靶机的路由信息(datatype 4,只读)。
| Name | Required | Description | Default |
|---|---|---|---|
| port | No | ||
| targets | Yes |
TDQS
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.
version_queryA
查询多台靶机的 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 |
TDQS
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.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
4 tool updates
v0.1.0- First observed
isfile - First observed
list_targets - First observed
routeinfo - First observed
version_query
TDQS
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.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
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.
Personal assistant MCP server with search, execute, packages, jobs, secrets, and integrations.
MCP server for Pentest-Tools.com: run scans, manage findings and reports via your preffered LLM.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceAn MCP server that allows LLMs to create, configure, validate, and explain Cisco Packet Tracer network topologies. It provides a comprehensive suite of tools for generating deployment scripts, CLI configurations, and automated network troubleshooting.153MIT
- AlicenseNot gradedqualityDmaintenanceA modular MCP server providing file operations, web search, URL scraping, and sandboxed command execution for LLM interactions.1MIT
- AlicenseBqualityCmaintenanceMCP server for Packmate, a CTF network traffic analyzer, enabling LLMs to analyze network traffic streams, search patterns, and manage pcap files.16MIT

Itential MCP Serverofficial
AlicenseBqualityAmaintenanceMCP server for connecting LLMs to Itential Platform, enabling network automation, workflow orchestration, and platform monitoring.7635GPL 3.0
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/weihang1258/mcp_socket_server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server