AI导哈

模型上下文协议服务器

MCP服务器是一个提供安全访问文件系统、系统信息、Obsidian仓库、SQLite数据库和UniFi网络控制器工具的自定义协议服务器。

  • by Shawn-Falconbury
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 Shawn-Falconbury/mcp-server

使用说明

MCP 服务器

习俗 模型上下文协议（MCP） 服务器，为Claude Code和其他MCP客户端提供对文件系统、系统信息、黑曜石保险库、SQLite数据库和UniFi网络控制器工具的安全访问。

特性

  • 文件系统工具 -在允许的路径内读取、写入、列出和搜索文件
  • 系统工具 -获取系统信息，运行白名单命令，查看进程和磁盘使用情况
  • 黑曜石工具 -在vault中列出笔记、阅读内容、搜索文本和查找反向链接
  • 数据库工具 -以只读访问方式查询SQLite数据库
  • UniFi工具 -查询和管理UniFi Dream Machine网络，包括威胁管理（CyberSecure）

安全

  • 带TLS证书的HTTPS（支持Let's Encrypt）
  • 所有MCP请求的承载令牌身份验证
  • 文件系统操作的路径限制
  • 系统操作的命令白名单
  • 具有查询筛选功能的只读数据库访问
  • 用于UniFi集成的API密钥验证

需求

  • Node.js 18+（用于本机获取支持）
  • npm或纱线
  • TLS证书（用于开发的自签名，用于生产的Let’s Encrypt）
  • 可选：带API密钥的UniFi Dream Machine

安装

  1. 克隆存储库：

    git clone https://github.com/your-username/mcp-server.git
cd mcp-server

  2. 安装依赖项：

    npm install

  3. 配置环境：

    cp .env.example .env
# Edit .env with your settings

  4. 生成TLS证书（用于开发）：

    mkdir -p certs
openssl req -x509 -newkey rsa:4096 -keyout certs/server.key -out certs/server.crt -days 365 -nodes -subj "/CN=localhost"

  5. 构建并运行：

    npm run build
npm start

配置

复制 .env.example 到 .env 并配置：

变量 必填 描述
MCP_TOKEN 是 MCP客户端的身份验证令牌
MCP_PORT 否 服务器端口（默认值：8443）
USE_HTTPS 否 使用HTTPS（默认值：true）
SSL_CERT_PATH 否 SSL证书的路径
SSL_KEY_PATH 否 SSL私钥路径
ALLOWED_PATHS 否 文件系统访问的逗号分隔路径
OBSIDIAN_VAULT_PATH 否 黑曜石拱顶路径
DB_PATH 否 SQLite数据库的路径
UNIFI_HOST 否 UniFi控制器IP/主机名
UNIFI_API_KEY 否 UniFi API密钥
UNIFI_SITE 否 UniFi站点名称（默认：“默认”）

用法

发展

npm run dev    # Run with tsx (hot reload)

生产

npm run build  # Compile TypeScript
npm start      # Run compiled server

系统化服务

创建 /etc/systemd/system/mcp-server.service:

[Unit]
Description=MCP Server
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/mcp-server
ExecStart=/usr/bin/npm start
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

然后：

sudo systemctl daemon-reload
sudo systemctl enable mcp-server
sudo systemctl start mcp-server

连接客户

克劳德代码（CLI）

claude mcp add --transport http my-mcp https://your-server.example.com:8443/mcp \
  --header "Authorization: Bearer YOUR_MCP_TOKEN"

或添加到您的项目 .mcp.json:

{
  "mcpServers": {
    "my-mcp": {
      "url": "https://your-server.example.com:8443/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

克劳德桌面版

添加到您的Claude Desktop配置文件中：

  • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
  • 窗户： %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "my-mcp": {
      "url": "https://your-server.example.com:8443/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

保存后重新启动Claude Desktop。

可用工具

看 docs/tools-reference.md 获取完整的工具文档。

工具类别

类别 工具 描述
文件系统 4 文件读/写/列表/搜索
系统 4 系统信息和命令
黑曜石 4 保险库笔记和搜索
数据库 3 SQLite查询
UniFi 19 网络管理和安全

总计：34个工具

项目结构

mcp-server/
├── src/
│   ├── index.ts          # Entry point
│   ├── server.ts         # Express + MCP setup
│   ├── auth.ts           # Token authentication
│   └── tools/
│       ├── index.ts      # Tool registry
│       ├── filesystem.ts # File operations
│       ├── system.ts     # System commands
│       ├── obsidian.ts   # Obsidian vault
│       ├── database.ts   # SQLite queries
│       └── unifi.ts      # UniFi controller
├── docs/                 # Documentation
├── certs/                # TLS certificates (not in repo)
├── dist/                 # Compiled output (not in repo)
├── .env                  # Configuration (not in repo)
└── .env.example          # Example configuration

API终点

服务器提供两种访问工具的方式：

REST API（简单）

无需MCP协议握手即可直接访问工具。最适合脚本、自动化和测试。

端点 方法 身份验证 描述
/health GET 否 健康检查
/api/tools GET 是 列出所有具有模式的可用工具
/api/tools/:name GET 是 获取特定工具的信息
/api/tools/:name POST 是 执行一个工具（请求体中的参数）

示例-调用工具的单个请求：

curl -X POST https://your-server.example.com:8443/api/tools/unifi_get_network_health \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

响应格式：

{
  "success": true,
  "tool": "unifi_get_network_health",
  "data": { ... }
}

MCP协议（完整）

带会话管理的标准MCP协议。克劳德代码和克劳德桌面需要。

端点 方法 身份验证 描述
/mcp GET 是 服务器信息
/mcp POST 是 MCP协议消息
/mcp DELETE 是 关闭会话

许可证

ISC

贡献

欢迎投稿！请随时提交问题和拉取请求。

相关 MCP