AI导哈

模型上下文协议服务器

Synapse MCP是一个基于FastMCP框架的生产级模型上下文协议服务器，提供用户认证、管理界面和细粒度权限控制，适用于与Open WebUI等MCP兼容的LLM客户端集成。

  • by John-Dekka
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 John-Dekka/Synapse-MCP

使用说明

⚡ Synapse MCP

生产准备就绪 模型上下文协议（MCP） 服务器构建于 FastMCP，具有用户身份验证、管理员管理和每个工具的权限控制功能。建造于 约翰·德卡设计用于集成 打开WebUI，以及其他MCP兼容的LLM客户端。

特性

  • 🔐 承载令牌身份验证 -MCP请求的安全HTTP级身份验证
  • 👥 用户管理 -管理员仪表板用于注册、启用/禁用用户
  • 🛠️ 权限控制 -按用户、按工具进行细粒度访问控制
  • 🌐 web界面 -FastAPI驱动的管理面板，采用现代深色主题
  • 📦 SQLite数据库 -轻量级、基于文件的存储（无外部依赖）
  • ⚡ FastMCP 2.x -基于最新的FastMCP框架构建
  • 🎯 单用户模式 -可选的简化模式，无需身份验证

快速开始

1.克隆和设置

git clone https://github.com/John-Dekka/Synapse-MCP.git
cd Synapse-MCP

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

2.配置环境（可选）

复制示例环境文件并根据需要进行自定义：

cp .env_example .env

编辑 .env 更改端口、数据库位置或安全设置。看 配置 了解详情。

3.运行服务器

python run.py

多用户模式输出：

==================================================
🚀 Synapse MCP
==================================================
📦 Initializing database...
✅ Database ready!
🔑 Generated new SECRET_KEY and saved to .env

🌐 Web interface: http://0.0.0.0:5000
🔌 MCP server: http://0.0.0.0:8000

📝 Register at the web interface to create an admin account.
==================================================

单用户模式输出：

==================================================
🚀 Synapse MCP
==================================================
📦 Initializing database...
✅ Database ready!

🔒 SINGLE USER MODE: Authentication disabled
🔌 MCP server: http://0.0.0.0:8000

📝 No API key required - all tools available
==================================================

首次设置

多用户模式设置

创建管理员帐户

  1. 打开 http://localhost:5000/register 在浏览器中
  2. 这 第一用户 自动注册成为 管理员
  3. 您将被重定向到管理员仪表板

添加常规用户

  1. 新用户在以下网址注册 /register
  2. 他们必须等待管理员批准
  3. 管理员从仪表板启用用户
  4. 管理员向每个用户授予工具权限

单用户模式设置

无需设置！只需运行服务器并立即开始使用工具：

  1. 集 SINGLE_USER_MODE=True 在你的 .env 文件
  2. 跑 python run.py
  3. 将LLM客户端连接到 http://localhost:8000/mcp （无需身份验证）
  4. 所有工具均自动可用

🎯 非常适合个人使用、开发或测试场景！

与LLM客户端一起使用

打开WebUI配置

多用户模式：

在Open WebUI的MCP设置中：

设置 值
服务器URL http://localhost:8000/mcp
认证 承载令牌
代币 <your-api-token-from-dashboard>

单用户模式：

在Open WebUI的MCP设置中：

设置 值
服务器URL http://localhost:8000/mcp
认证 没有
代币 （留空）

获取您的API代币

仅限多用户模式：

  1. 登录到web界面 http://localhost:5000
  2. 您的令牌显示在仪表板上
  3. 使用 复制 复制按钮
  4. 使用 再生 创建新令牌（使旧令牌无效）

💡 单用户模式注释：不需要API令牌。所有工具对任何客户端都是自动可用的。

其他MCP客户端

多用户模式：

对于任何兼容MCP的客户端，配置：

  • 运输：HTTP（流式HTTP）
  • 统一资源定位符: http://<server-ip>:8000/mcp
  • 认证头: Bearer <your-api-token>

单用户模式：

对于任何兼容MCP的客户端，配置：

  • 运输：HTTP（流式HTTP）
  • 统一资源定位符: http://<server-ip>:8000/mcp
  • 认证头: （无需）

可用工具

工具 说明
get_current_time 获取当前日期和时间
get_article 将网络文章提取并清理到Markdown

示例工具调用

连接后，您的法学硕士可以致电：

Get the current time

MCP服务器将执行 get_current_time().

配置

所有配置都是通过环境变量完成的。复制 .env_example 到 .env 并自定义：

单用户模式

变量 默认值 描述
SINGLE_USER_MODE False 设置为 True 禁用身份验证和管理界面。不需要API密钥，所有工具都可用，web界面无法启动。

数据库

变量 默认值 描述
DATABASE_URL sqlite:///mcp.db SQLite数据库路径

安全

变量 默认值 描述
SECRET_KEY （自动生成） 会话加密密钥。首次运行时自动生成并保存到 .env
TOKEN_EXPIRY_DAYS 30 API令牌到期前的不活动天数（滑动窗口）

💡 滑动到期：令牌每次使用时都会自动延长其到期时间。令牌仅在30天后过期 无活性.

⚠️ 单用户模式注释：何时 SINGLE_USER_MODE=True，the SECRET_KEY 和 TOKEN_EXPIRY_DAYS 由于不执行身份验证，因此忽略设置。

服务器端口

变量 默认值 描述
WEB_HOST 0.0.0.0 Web界面绑定地址（在单用户模式下忽略）
WEB_PORT 5000 Web接口端口（在单用户模式下忽略）
MCP_HOST 0.0.0.0 MCP服务器绑定地址
MCP_PORT 8000 MCP服务器端口

项目结构

Synapse-MCP/
├── run.py              # Entry point - runs both servers
├── config.py           # Configuration from environment
├── database.py         # SQLAlchemy models (User, APIToken, ToolPermission)
├── auth.py             # Authentication utilities
├── mcp_server.py       # FastMCP server with tools
├── web_app.py          # FastAPI admin interface
├── requirements.txt    # Python dependencies
├── .env_example        # Example environment configuration
├── mcp.db              # SQLite database (created on first run)
└── templates/          # Jinja2 HTML templates
    ├── base.html       # Base template with styling
    ├── index.html      # Login page
    ├── register.html   # Registration page
    ├── dashboard.html  # User dashboard (shows API token)
    ├── admin.html      # Admin user management
    └── permissions.html# Tool permission management

添加新工具

要添加新的MCP工具：

  1. 定义工具 在 mcp_server.py:
@mcp.tool()
def my_new_tool(
    param1: Annotated[str, "Description of param1"],
    param2: Annotated[int, "Description of param2"] = 10
) -> str:
    """
    Tool description for the LLM.
    """
    check_permission("my_new_tool")  # Enforce permission check
    
    # Your tool logic here
    return f"Result: {param1}, {param2}"
  1. 注册该工具 在 auth.py:
AVAILABLE_TOOLS = ["get_current_time", "my_new_tool"]
  1. 重新启动服务器 并通过管理仪表板向用户授予权限。

安全考虑

⚠️ 对于生产部署：

  • 使用HTTPS -使用TLS设置反向代理（nginx、Caddy）
  • 限制 *_HOST -使用 127.0.0.1 如果只需要本地访问
  • 备份数据库 - mcp.db 包含所有用户数据
  • 保护 .env -包含自动生成的SECRET_KEY
  • 查看令牌到期 -调整 TOKEN_EXPIRY_DAYS 基于安全需求

故障排除

运行时出现“ModuleNotFoundError”

确保虚拟环境已激活：

source venv/bin/activate  # or: ./venv/bin/python run.py

Python别名覆盖venv

如果你有shell别名 python，使用显式的venv路径：

./venv/bin/python run.py

令牌在Open WebUI中不起作用

  1. 验证用户是否 启用 在管理仪表板中
  2. 检查用户是否 权限 对于工具
  3. 确保令牌没有 过期 （必要时重新生成）
  4. 确认URL为 http://host:8000/mcp （不是端口5000）

许可证

GNU v3-有关详细信息，请参阅LICENSE文件。

相关 MCP