Skip to main content
Glama
AndersHsueh

AX Local Operations MCP Server

by AndersHsueh
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Local

AX本地操作 MCP 服务器 v2.6.0

一个功能强大的 MCP (Model Context Protocol) 服务器，名为 ax_local_operations，为大模型应用提供安全的本地文件操作、行级编辑、文件搜索、文件比较、文件哈希、文件权限、文件压缩、文件监控、命令执行和任务管理功能。

作者本人推荐,特点:

  • 使用这个ax_local_operations，你可以在任何接受MCP的对话应用里, 把它变成可以操作电脑的助手. 而不仅仅是一个对话聊天工具.

  • 最佳实践: 使用 Qwen 应用, 加入 ax_local_operations 这个MCP之后, qwen 可以接受用户的指示, 从而完成一些诸如编码, 部署环境, 检测设备硬件等等的实际工作. 而不是仅仅聊天. 还可以使用 Jan,lmStudio 这些应用都可以加入ax_local_operations 这个MCP之后，从而实现更智能的助手功能。

  • 对比其它MCP, 比如其它的本地文件MCP, 专注于文件操作. 但没有命令执行工具，所以这个MCP适合做对话应用，而不是命令行工具。

使用注意,:

  • 在对话中建议第一句就告诉AI: "当前的工作目录是: /User/research/work", 这样可以让AI在工作中使用临时写入文件不必影响原设备环境.

🌐 平台兼容性

支持的平台

平台

支持状态

说明

macOS

✅ 完全支持

所有工具均可正常使用

Linux

✅ 完全支持

所有工具均可正常使用（包括 sudo_config）

Windows

✅ 基本支持

11个工具可用，2个工具部分支持

工具平台支持详情

完全跨平台支持（Windows/macOS/Linux）

以下工具在所有平台上均可正常使用：

  • ✅ file_operation - 文件操作

  • ✅ file_edit - 文件编辑

  • ✅ file_search - 文件搜索

  • ✅ file_compare - 文件比较

  • ✅ file_hash - 文件哈希

  • ✅ file_permissions - 文件权限管理（使用系统对应的命令：attrib/icacls 或 chmod）

  • ✅ file_watch - 文件监控

  • ✅ execute_command - 命令执行

  • ✅ task_manager - 任务管理

  • ✅ time_tool - 时间工具

  • ✅ environment_memory - 环境记忆

平台限制

file_archive - 文件压缩工具

  • macOS/Linux: ✅ 完全支持（使用系统命令 zip/unzip/tar/gzip）

  • Windows: ⚠️ 需要安装额外工具

    • 需要安装 Git Bash、WSL 或第三方压缩工具

    • 或手动安装 zip/unzip/tar/gzip 命令行工具

sudo_config - Sudo配置工具

  • Linux: ✅ 完全支持

  • macOS: ❌ 不支持（不适用）

  • Windows: ❌ 不支持（不适用）

Windows 用户注意事项

  1. 路径格式: 使用反斜杠 \ 或正斜杠 / 均可，Node.js 会自动处理

  2. 权限管理: 使用 Windows 原生的 attrib 和 icacls 命令

  3. 压缩工具: 如需使用 file_archive，建议：

    • 安装 Git for Windows（自带 Bash 和常用工具）

    • 或使用 WSL (Windows Subsystem for Linux)

    • 或安装 7-Zip 并将其添加到系统 PATH

🔧 开发者与 API 状态概览

本项目已完成核心工具的参数别名与统一输出格式重构（API-001 / API-002 进入“接近完成”阶段）：

标准

描述

状态

API-001

参数别名统一（path/file_path/dir_path 等）

NEAR DONE

API-002

统一输出格式：`output_format = text

json

both`

NEAR DONE

剩余仅为边缘场景再审阅与未来可选增强（例如更精细的 diff 输出拆分、搜索流式增量返回等）。

开发新增工具请阅读：tools/tools_dev_guide.md（已提供安全、参数、输出、测试、Checklist 全量规范）。

统一输出机制简述

所有工具通过 output_format 控制输出：

  • text：人类可读摘要

  • json：结构化数据（适合上层模型二次推理/程序化处理）

  • both：同时返回（先文本后 JSON）

典型调用示例（文件比较）：

{ "name": "file_compare", "arguments": { "file1": "/path/to/a.js", "file2": "/path/to/b.js", "output_format": "both" } }

典型 JSON 片段（仅示例）：

{ "action": "compare", "left": "/path/to/a.js", "right": "/path/to/b.js", "diff_stats": { "added": 12, "removed": 4, "modified": 3 } }

搜索工具示例（限制深度 + 超时 + 忽略策略）：

{ "name": "file_search", "arguments": { "search_path": "src", "pattern": "class ", "max_depth": 6, "timeout_ms": 4000, "ignore": ["node_modules", "*.log"], "output_format": "json" } }

若结果被截断（大小/超时/数量），JSON 中会包含 truncated: true 或 timed_out: true 等标记字段。

✨ 功能特性

📁 文件操作工具

  • 读取文件 - 安全读取本地文件内容

  • 写入文件 - 创建或更新文件内容

  • 列出目录 - 查看目录结构和文件列表

  • 创建目录 - 创建新的目录结构

  • 删除文件/目录 - 安全删除文件和目录

✏️ 文件编辑工具 (v1.1.0 新增)

  • 删除行 - 删除指定行号范围的内容

  • 插入行 - 在指定位置插入新内容

  • 替换行 - 替换指定行号范围的内容

  • 追加行 - 在文件末尾追加新内容

🔍 文件搜索工具 (v1.2.0 新增)

  • 内容搜索 - 在文件中搜索指定内容

  • 正则表达式 - 支持正则表达式搜索

  • 文件类型过滤 - 按文件类型过滤搜索结果

  • 大小写控制 - 支持区分/不区分大小写搜索

📊 文件比较工具 (v1.2.0 新增)

  • 差异对比 - 比较两个文件的差异

  • 行级对比 - 显示具体的行级差异

  • 多种输出格式 - 支持文本和JSON格式输出

🔐 文件哈希工具 (v1.2.0 新增)

  • 多种算法 - 支持MD5、SHA1、SHA256、SHA512

  • 文件完整性 - 验证文件完整性

  • 快速计算 - 高效的文件哈希计算

🛡️ 文件权限工具 (v1.2.0 新增)

  • 权限修改 - 修改文件权限

  • 递归应用 - 支持递归应用权限

  • 权限显示 - 显示详细的权限信息

📦 文件压缩工具 (v1.2.0 新增)

  • 多种格式 - 支持ZIP、TAR、GZ、TAR.GZ格式

  • 压缩解压 - 支持压缩和解压操作

  • 批量处理 - 支持目录批量压缩

👁️ 文件监控工具 (v1.2.0 新增)

  • 实时监控 - 监控文件变化

  • 事件类型 - 支持创建、删除、修改事件

  • 定时监控 - 可设置监控时长

📋 任务管理工具 (v2.0.1 新增)

  • 任务分解 - 支持创建复杂任务和子任务

  • 优先级管理 - 支持低、中、高、紧急四个优先级

  • 进度跟踪 - 实时跟踪任务完成进度

  • 排期管理 - 支持设置截止日期

  • 状态管理 - 待处理、进行中、已完成、已取消

  • 模型隔离 - 不同模型拥有独立的任务列表

🧠 环境记忆工具 (v2.1.0 新增)

  • 环境信息管理 - 自动读取和存储环境变量信息

  • 动态更新 - 识别会话中的环境相关信息并自动记录

  • 智能使用 - 根据会话上下文智能使用记忆的环境信息

  • 文件存储 - 信息存储在 ~/.local_file_operations/.env 文件中

⚡ 命令执行工具

  • 执行本地命令 - 在指定工作目录下执行系统命令

  • 安全限制 - 自动过滤危险命令，保护系统安全

🔒 安全特性

🕒 时间工具 (v2.0.2 新增)

  • 当前时间 - 获取当前真实时间

  • 多种格式 - ISO、RFC3339、UNIX(秒/毫秒)、本地格式

  • 时区支持 - 指定 IANA 时区（如 Asia/Shanghai）

  • 路径限制 - 禁止访问敏感系统目录

  • 命令过滤 - 阻止执行危险的系统命令

  • 权限控制 - 确保操作在安全范围内

🚀 快速开始

环境要求

  • Node.js >= 18.0.0

  • npm 或 yarn

安装依赖

cd /Users/abc/research/mcp npm install

📋 配置说明

LM Studio 配置

{ "mcpServers": { "ax_local_operations": { "command": "/Users/abc/.nvm/versions/node/v22.16.0/bin/node", "args": ["/Users/abc/research/mcp/index.js"], "env": { "PATH": "/Users/abc/.nvm/versions/node/v22.16.0/bin:/usr/local/bin:/usr/bin:/bin", "NODE_PATH": "/Users/abc/research/mcp" } } } } ### 注意这里的 "/Users/abc/research/mcp" 是下载到的文件夹的位置.要改成自己的路径.

Qwen 配置

{ "mcpServers": { "ax_local_operations": { "command": "npx", "args": [ "-y", "ax-local-operations-mcp@file:/Users/abc/research/mcp" ], "env": { "NODE_PATH": "/Users/abc/research/mcp", "PATH": "/Users/abc/.nvm/versions/node/v22.16.0/bin:/usr/local/bin:/usr/bin:/bin" } } } } ### 注意这里的 "ax-local-operations-mcp@file:/Users/abc/research/mcp" @file: 后面是下载到的文件夹的位置.要改成自己的路径.

🛠️ 工具使用

文件操作工具

工作目录概念

为了安全性和灵活性，MCP服务器支持工作目录概念：

  • 工作目录：通过 working_directory 参数指定一个安全的基础目录

  • 相对路径：在 path 参数中使用相对路径，会自动基于工作目录解析

  • 智能检测：自动识别常见的项目目录模式，支持直接使用绝对路径

  • 安全限制：只有在允许的项目目录下的操作才被允许

  • 跨平台兼容：不硬编码特定路径，适用于不同用户和系统

允许的项目目录模式

系统自动识别以下目录模式，允许直接使用绝对路径：

  • /isoftstone/ - 项目目录

  • /Desktop/ - 桌面

  • /Documents/ - 文档

  • /Downloads/ - 下载

  • /Projects/ - 项目

  • /Workspace/ - 工作空间

  • /Code/ - 代码

  • /Development/ - 开发

  • /Work/ - 工作

  • /Study/ - 学习

  • /Research/ - 研究

读取文件

{ "name": "file_operation", "arguments": { "operation": "read", "path": "/path/to/file.txt" } }

写入文件

{ "name": "file_operation", "arguments": { "operation": "write", "path": "/path/to/file.txt", "content": "文件内容" } }

列出目录

{ "name": "file_operation", "arguments": { "operation": "list", "path": "/path/to/directory" } }

创建目录

{ "name": "file_operation", "arguments": { "operation": "create_dir", "path": "/path/to/new/directory" } }

使用工作目录（推荐）

{ "name": "file_operation", "arguments": { "operation": "create_dir", "path": "售前类业务/自动HMI", "working_directory": "/Users/abc/isoftstone" } }

删除文件/目录

{ "name": "file_operation", "arguments": { "operation": "delete", "path": "/path/to/file_or_directory" } }

文件编辑工具

删除行

{ "name": "file_edit", "arguments": { "operation": "delete_lines", "path": "/path/to/file.txt", "start_line": 3, "end_line": 5 } }

插入行

{ "name": "file_edit", "arguments": { "operation": "insert_lines", "path": "/path/to/file.txt", "start_line": 3, "content": "新插入的内容" } }

替换行

{ "name": "file_edit", "arguments": { "operation": "replace_lines", "path": "/path/to/file.txt", "start_line": 3, "end_line": 5, "content": "替换后的内容" } }

追加行

{ "name": "file_edit", "arguments": { "operation": "append_lines", "path": "/path/to/file.txt", "content": "追加到文件末尾的内容" } }

命令执行工具

执行命令

{ "name": "execute_command", "arguments": { "command": "ls -la", "working_directory": "/path/to/working/dir" } }

文件搜索工具

搜索文件内容

{ "name": "file_search", "arguments": { "search_path": "/path/to/search", "pattern": "function.*\\(", "file_types": "js,ts", "case_sensitive": false, "max_results": 50, "max_depth": 8, "timeout_ms": 5000, "ignore": ["node_modules", "*.log"] } }

参数新增说明：

  • max_depth (默认 8)：限制目录递归深度，防止深层/循环结构拖慢搜索。

  • timeout_ms (默认 5000)：整体搜索的软超时，超时后会提前结束并返回已收集结果（结尾标注“超时截断”）。

  • ignore：可忽略的文件/目录通配（支持前缀/后缀 * 简单匹配，如 *.log、build*、*cache）。

文件比较工具

比较两个文件

{ "name": "file_compare", "arguments": { "file1": "/path/to/file1.txt", "file2": "/path/to/file2.txt", "output_format": "text" } }

文件哈希工具

计算文件哈希

{ "name": "file_hash", "arguments": { "path": "/path/to/file.txt", "algorithm": "sha256" } }

文件权限工具

修改文件权限

{ "name": "file_permissions", "arguments": { "path": "/path/to/file.txt", "mode": "755", "recursive": false } }

文件压缩工具

压缩文件

{ "name": "file_archive", "arguments": { "operation": "compress", "source": "/path/to/source", "destination": "/path/to/archive.zip", "format": "zip" } }

解压文件

{ "name": "file_archive", "arguments": { "operation": "extract", "source": "/path/to/archive.zip", "destination": "/path/to/extract" } }

文件监控工具

监控文件变化

{ "name": "file_watch", "arguments": { "path": "/path/to/watch", "events": "create,delete,modify", "duration": 60, "output_format": "text" } }

任务管理工具

时间工具

获取当前时间（ISO，含毫秒）

{ "name": "time_tool", "arguments": { "format": "iso", "include_milliseconds": true } }

获取 UNIX 时间戳（秒）

{ "name": "time_tool", "arguments": { "format": "unix" } }

获取本地时间并指定时区

{ "name": "time_tool", "arguments": { "format": "locale", "time_zone": "Asia/Shanghai", "include_milliseconds": false } }

创建任务

{ "name": "task_manager", "arguments": { "operation": "create", "model_name": "claude-3.5-sonnet", "title": "完成项目文档", "description": "编写API文档和使用说明", "priority": "high", "due_date": "2024-01-15T10:00:00Z", "subtasks": ["编写API文档", "创建使用示例", "更新README"] } }

列出任务

{ "name": "task_manager", "arguments": { "operation": "list", "model_name": "claude-3.5-sonnet", "status": "pending" } }

更新任务

{ "name": "task_manager", "arguments": { "operation": "update", "model_name": "claude-3.5-sonnet", "task_id": "task_1758140089301_bi4kwqkcl", "status": "in_progress", "progress": 50 } }

完成任务

{ "name": "task_manager", "arguments": { "operation": "complete", "model_name": "claude-3.5-sonnet", "task_id": "task_1758140089301_bi4kwqkcl" } }

🔧 工作原理

MCP 协议通信

  1. 大模型应用启动 - 根据配置自动启动 MCP 服务器进程

  2. 建立连接 - 通过 stdio 协议建立通信连接

  3. 工具发现 - 大模型应用发送 ListTools 请求获取可用工具

  4. 工具调用 - 当需要文件操作时，发送工具调用请求

  5. 自动管理 - 大模型应用负责管理 MCP 服务器的生命周期

安全机制

本服务器采用分层安全模型：

  1. 路径沙箱

  • 仅允许访问用户主目录及其子目录（相对路径会被解析到用户 home）。

  • 所有工具统一调用 securityValidator.resolveAndAssert() 进行归一化解析与主目录断言。

  • 非法越界将返回错误码 E_PATH_DENIED。

  1. 命令策略（Phase 0 重构后）

  • 使用 lib/commandPolicy.js：正则匹配分级 deny | warn | allow。

  • deny：抛出 E_DANGEROUS_CMD；warn：需调用方添加 { "confirm": true } 复确认。

  • 典型 deny：passwd；典型 warn：rm -rf, sudo, chown, chmod 777。

  1. 错误与输出统一

  • 错误通过自定义 ToolError(code, message) 抛出。

  • 主要错误码：

    • E_PATH_DENIED 路径不允许

    • E_NOT_FOUND 文件/目录不存在

    • E_INVALID_ARGS 参数或操作无效

    • E_DANGEROUS_CMD 危险命令

    • E_LIMIT_REACHED 递归/资源限制

  • 输出封装：responses.text() / responses.json() / responses.both()。

  1. 递归深度限制

  • file_permissions 工具递归模式默认 max_depth = 5，超过抛 E_LIMIT_REACHED。

  1. 压缩/解压安全

  • 使用 child_process.spawn 参数数组替换字符串拼接，降低命令注入风险。

  1. 未来计划（Phase 1+）

  • file_search 增加 max_depth、timeout_ms 与 ignore 列表

  • 工具注册解耦 & 生命周期钩子

若需要在企业内部开放更宽权限，可在外层代理做白名单前置，再调用此 MCP。

标准行为变化（自 v2.1.0-alpha.1 起）

变更

旧行为

新行为

路径解析

各工具独立解析

统一 home 基础 + 断言

危险命令

简单 substring 检测

策略分级 + confirm 机制

错误格式

抛普通 Error 文本

ToolError 结构化（内部）

压缩执行

拼接命令字符串

spawn 参数数组

递归权限

无深度限制

默认最大 5 层

示例：高风险命令确认

{ "name": "execute_command", "arguments": { "command": "rm -rf tmp_cache", "confirm": true } }

示例：递归权限并限制深度

{ "name": "file_permissions", "arguments": { "path": "project", "mode": "755", "recursive": true, "max_depth": 3 } }

📁 项目结构

mcp/ ├── index.js # MCP 服务器主文件 ├── package.json # Node.js 项目配置 ├── mcp_config.json # LM Studio 配置 ├── qwen_config_final.json # Qwen 配置 ├── mcp_config_template.json # 配置模板 ├── tools/ # 工具模块目录 │ ├── fileOperation.js # 文件操作工具 │ ├── fileEdit.js # 文件编辑工具 │ ├── fileSearch.js # 文件搜索工具 │ ├── fileCompare.js # 文件比较工具 │ ├── fileHash.js # 文件哈希工具 │ ├── filePermissions.js # 文件权限工具 │ ├── fileArchive.js # 文件压缩工具 │ ├── fileWatch.js # 文件监控工具 │ ├── commandExecution.js # 命令执行工具 │ ├── taskManager.js # 任务管理工具 │ ├── timeTool.js # 时间工具 │ ├── environmentMemory.js # 环境记忆工具核心模块 │ ├── environmentMemoryAdapter.js # 环境记忆工具适配器 │ └── securityValidator.js # 安全验证模块 ├── temps/ # 临时文件目录（自动创建） │ └── todo_<model_name>.json # 任务数据存储（运行时生成） ├── share4u.md # 中文分享文档 ├── share4u_en.md # 英文分享文档 ├── share4u_jp.md # 日文分享文档 └── README.md # 项目文档

🎯 支持的大模型应用

  • ✅ LM Studio - 使用直接 node 执行

  • ✅ Qwen - 使用 npx 本地包

  • ✅ 其他支持 MCP 协议的应用

🔍 故障排除

常见问题

  1. 连接失败 - 检查 Node.js 路径和文件权限

  2. 工具不可用 - 确认 MCP 服务器正常启动

  3. 权限错误 - 检查文件系统权限

调试方法

  1. 手动测试 - 运行 npx -y ax-local-operations-mcp@file:/Users/abc/research/mcp

  2. 检查日志 - 查看大模型应用的错误日志

  3. 验证配置 - 确认配置文件格式正确

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

享受强大的本地文件操作能力！ 🚀✨

📚 版本历史

v2.6.0 (2025-02-04)

  • 添加 MCP annotations 支持（readOnlyHint, destructiveHint 等）

  • 添加 isError 标记到错误响应

  • 重构命令执行为 spawn 模式提高安全性

  • 添加 outputSchema 定义支持响应验证

  • 完善参数描述和使用示例

  • 添加文件大小限制（10MB）和截断处理

  • 新增 CLAUDE.md 为 AI 开发提供指导

v2.5.0 (2025-12-05)

  • 将版本号从 2.4.1 升级到 2.5.0

  • 各种功能更新和改进

v2.1.0-alpha.1 (预发布)

  • 路径解析与安全校验统一（pathUtils + securityValidator.resolveAndAssert）

  • 命令执行引入策略分级（deny/warn/allow）

  • 新增统一错误模块 errors.js 与响应封装 responses.js

  • file_archive 使用 spawn 避免命令注入

  • file_permissions 增加递归深度限制（默认 5）

  • 为后续重构（工具注册 / 性能限制）奠定基础

v2.1.0 (2024-09-25)

  • 新增环境记忆工具，用于管理环境变量信息

  • 支持自动读取和存储环境信息

  • 支持动态更新环境信息

环境记忆工具使用示例

读取环境信息
{ "name": "environment_memory", "arguments": { "operation": "read" } }
更新环境信息
{ "name": "environment_memory", "arguments": { "operation": "update", "key": "PROJECT_PATH", "value": "/Users/username/projects/myproject" } }
获取特定环境变量
{ "name": "environment_memory", "arguments": { "operation": "get", "key": "PROJECT_PATH" } }

v2.0.2 (2024-01-15)

  • 新增时间工具，支持获取当前时间

  • 支持多种时间格式（ISO、RFC3339、UNIX、本地格式）

  • 支持时区设置

v2.0.1 (2024-01-10)

  • 新增任务管理工具

  • 支持任务创建、更新、完成等操作

  • 支持优先级管理和进度跟踪

  • 支持模型隔离的任务管理

v1.2.0 (2023-12-20)

  • 新增文件搜索工具

  • 新增文件比较工具

  • 新增文件哈希工具

  • 新增文件权限工具

  • 新增文件压缩工具

  • 新增文件监控工具

v1.1.0 (2023-12-10)

  • 新增文件编辑工具

  • 支持行级编辑操作（删除、插入、替换、追加）

v1.0.0 (2023-12-01)

  • 初始版本发布

  • 支持基本文件操作（读取、写入、列出、创建、删除）

  • 支持命令执行工具

📦 安装与使用（无需下载源码）

支持通过 npm 全局安装或直接使用 npx 运行，无需手动克隆仓库或修改本地路径。

全局安装

npm install -g ax-local-operations-mcp

安装后，可在支持 MCP 的客户端中直接引用可执行文件 ax-local-operations-mcp。

直接使用 npx

无需安装，直接启动：

npx -y ax-local-operations-mcp

在 LM Studio 中使用

将可执行文件设置为 ax-local-operations-mcp（无需绝对路径）：

{ "mcpServers": { "ax_local_operations": { "command": "ax-local-operations-mcp" } } }

在 Qwen 中使用

使用 npx 直接调用（无需本地源码路径）：

{ "mcpServers": { "ax_local_operations": { "command": "npx", "args": ["-y", "ax-local-operations-mcp"] } } }

提示：若公司网络限制 npm，亦可发布到 GitHub Packages 或设置内部 npm 镜像，详见 dev.md 发布章节。

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

Tools

View all tools

New MCP Servers

Latest Blog Posts

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/AndersHsueh/Ax-LocalTools-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server