AI导哈

模型上下文协议服务器

一个无状态的、基于Docker的模型上下文协议（MCP）服务器，通过HTTP将本地机器的文件系统、git、shell、网络、数据库和系统暴露给任何兼容MCP的LLM客户端。

  • by basit-devBE
  • TypeScript
  • 本地部署
  • 7 星标
  • 更新于
在 GitHub 查看 basit-devBE/Local-MCP

使用说明

本地环境mcp

无状态、Docker化 模型上下文协议（MCP） 使用TypeScript构建的服务器。它通过HTTP将您的本地机器（文件系统、git、shell、网络、数据库和系统）暴露给任何与MCP兼容的LLM客户端。

在TypeScript中原生构建 @modelcontextprotocol/sdk 利用Express、Zod模式和完全解耦的分层架构。

快速开始

# 1. Clone and install
git clone <repo-url>
cd local-mcp
npm install

# 2. Build the TypeScript source
npm run build

# 3. Start the server (runs on port 3000 by default)
npm start

# OR Start with Docker (multi-stage build)
docker compose up -d --build

# 4. Expose via ngrok (in a separate terminal)
ngrok http 3001

# 5. Copy the ngrok URL and add to Claude.ai
# Settings → Integrations → Add MCP Server
# URL: https://your-ngrok-url.ngrok-free.app/mcp

目录

建筑

LLM Client (Claude / Cursor / API)
        │  HTTPS POST /mcp
        ▼
   Express Routing Layer (src/app.ts)
        │
        ├── GET  /health → System Checks
        ├── POST /mcp    → Create Server Session
        ├── GET  /mcp    → Resume Session
        └── DELETE /mcp  → Purge Session
               │
               ▼
   Layered Tool Registry (src/tools/registry.ts)
               │
 ┌─────────┬───┴─────┬─────────┬─────────┬─────────┐
 ▼         ▼         ▼         ▼         ▼         ▼
 FS       Git      Network   Shell     System    Postgres
(9)      (11)       (8)       (9)       (8)       (3)

无状态模式：每个POST请求都会启动一个由单例会话管理器动态管理的新McpServer实例。

项目结构

从传统的单体JS迁移而来，该项目现在遵循一个严格类型的分层框架：

local-mcp/
├── src/
│   ├── server.ts               # Listener & bootstrap
│   ├── app.ts                  # Express routing & middleware wiring
│   ├── config.ts               # Zod-validated env loader (.env handled via dotenv)
│   ├── logger.ts               # Winston configuration
│   ├── routes/                 # Separated Controllers (health.ts, mcp.ts)
│   ├── services/               # Core Logic (processManager, sessionManager)
│   ├── types/                  # Shared TS definitions
│   └── tools/                  # All 48 MCP Tools separated by domain
│       ├── filesystem/         
│       ├── git/                
│       ├── network/            
│       ├── postgres/           # Dynamic Database capabilities
│       ├── shell/              
│       ├── system/             
│       └── registry.ts         # Injects toolsets into active MCP Sessions

传输和会话模型

使用 可流式传输的HTTP 运输。

路线 目的
POST /mcp 启动工具请求（工具/列表、工具/调用）——挂入新的或缓存的会话。
GET /mcp Streams服务器为连续客户端发送事件（SSE）。
DELETE /mcp 优雅地终止活动服务器。

工具参考

目前捆绑 48个本地工具 通过特定模块映射。

📁 文件系统

（所有路径相对于 FS_ROOT 防止目录遍历）

  • read_file, write_file, list_dir, make_dir, delete_path, copy_path, move_path, search_files, file_info

🌿 Git

（由简单的git提供支持，目标目录相对于 FS_ROOT)

  • git_status, git_diff, git_log, git_branch, git_add, git_commit, git_push, git_pull, git_clone, git_stash, git_show

🌐 网络

  • http_request, ping, dns_lookup, port_scan, whois, traceroute, download_file, check_connectivity

💻 外壳

（由注射者管理 ProcessManager 服务隔离内存中的生成日志）

  • run_command, spawn_process, list_processes, get_process_logs, kill_process, system_info, get_env, which, ps

🖥️ 系统

  • cron_list, disk_usage, open, notify, clipboard_write, clipboard_read, screenshot, list_installed

🐘 Postgres

（动态连接，而不是硬编码的全局连接）

  • pg_query：直接执行参数化的原始SQL查询。
  • pg_list_tables：枚举所有活动表，忽略系统架构。
  • pg_describe_table：询问目标模式表的类型格式、可空性和默认要求。

注意：Postgres工具要求您提供 connectionString 直接通过LLM接口进行参数设置，通过设计使服务器完全无需凭据。

环境变量

使用无缝处理 dotenv.

变量 必填 默认 描述
PORT 没有 3000 Express服务器绑定到的HTTP端口
FS_ROOT 没有 /host-home 文件操作的根目录。路径约束强制执行此边界。
MCP_AUTH_TOKEN 是（prod） （无） 承载身份验证令牌 X-MCP-Token.省略严重警告 dev 模式。
NODE_ENV 没有 development 设置为 production 强制执行令牌身份验证检查。

使用新工具进行扩展

使用模块化架构添加工具要容易得多：

  1. 在目标域层内创建严格类型的配置（例如。 src/tools/custom/myTool.ts):
import { z } from "zod";
import type { ToolDefinition } from "../../types/index.js";
import { ok } from "../../utils/response.js";

export const myCustomTool: ToolDefinition = {
  name: "custom_tool",
  description: "Does something specific",
  schema: {
    target: z.string().describe("What to target"),
  },
  handler: async ({ target }) => {
    return ok(`Executed logic on ${target}`);
  }
};
  1. 将工具数组导入并附加到 registerAllTools 在 src/tools/registry.ts.

安全模型

关注 缓解
路径遍历 safePath() 锚重重地靠在 FS_ROOT 界限。
秘密泄露 get_env 编辑隐藏标准密钥（机密/密码/api）的项目。
Docker隔离 以未挂载的方式本机运行 mcpuser 依靠安全的挂载点。
DB访问 动态处理，避免持久化 env 原木泄漏。

相关 MCP