Synapse MCP 服务器

模型上下文协议 (MCP) 服务器，公开 Synapse 实体（数据集、项目、文件夹、文件、表）及其注释并支持 OAuth2 身份验证。

概述

此服务器提供 RESTful API，用于通过模型上下文协议 (MCP) 访问 Synapse 实体及其注释。它允许您：

使用 Synapse 进行身份验证
通过 ID 检索实体
按名称检索实体
获取实体注释
获取实体子项
根据各种条件查询实体
查询 Synapse 表
获取 Croissant 元数据格式的数据集

安装

# Clone the repository
git clone https://github.com/SageBionetworks/synapse-mcp.git
cd synapse-mcp

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

# Install dependencies
pip install -e .

从 PyPI 安装

# Install from PyPI
pip install synapse-mcp

用法

启动服务器

python server.py --host 127.0.0.1 --port 9000

这将在默认端口（9000）上启动 MCP 服务器。

使用 CLI

# Start the server using the CLI
synapse-mcp --host 127.0.0.1 --port 9000 --debug

命令行选项

usage: server.py [-h] [--host HOST] [--port PORT] [--debug]

Run the Synapse MCP server with OAuth2 support

options:
 -h, --help show this help message and exit
 --host HOST Host to bind to
 --port PORT Port to listen on
 --debug Enable debug logging
 --server-url URL Public URL of the server (for OAuth2 redirect)

运行测试

# Run all tests with coverage
./run_tests.sh

# Or run pytest directly
python -m pytest

测试服务器

python examples/client_example.py

身份验证方法

环境变量

服务器支持以下环境变量：

HOST ：要绑定的主机（默认值：127.0.0.1）
PORT ：监听的端口（默认值：9000）
MCP_TRANSPORT ：要使用的传输协议（默认值：stdio）
- stdio ：使用标准输入/输出进行本地开发
- sse ：使用服务器发送事件进行云部署
MCP_SERVER_URL ：服务器的公共 URL（默认值：mcp://127.0.0.1:9000）
- 用于 OAuth2 重定向和服务器信息

服务器支持两种认证方式：

Auth Token ：使用 Synapse 身份验证令牌进行身份验证
OAuth2 ：使用 Synapse 的 OAuth2 服务器进行身份验证
- 需要在 Synapse 中注册 OAuth2 客户端（ https://www.synapse.org/#!PersonalAccessTokens:OAuth ）

API 端点

服务器信息

GET /info获取服务器信息

工具

GET /tools - 列出可用工具
POST /tools/authenticate - 使用 Synapse 进行身份验证
POST /tools/get_oauth_url - 获取 OAuth2 授权 URL
POST /tools/get_entity - 通过 ID 或名称获取实体
POST /tools/get_entity_annotations - 获取实体的注释
POST /tools/get_entity_children - 获取容器实体的子实体
POST /tools/query_entities - 根据各种条件查询实体
POST /tools/query_table - 查询 Synapse 表

资源

GET /resources - 列出可用资源
GET /resources/entity/{id} - 通过 ID 获取实体
GET /resources/entity/{id}/annotations - 获取实体注释
GET /resources/entity/{id}/children - 获取实体子项
GET /resources/query/entities/{entity_type} - 按类型查询实体
GET /resources/query/entities/parent/{parent_id} - 通过父 ID 查询实体
GET /resources/query/entities/name/{name} - 按名称查询实体
GET /resources/query/table/{id}/{query} - 使用类似 SQL 的语法查询表

OAuth2 端点

GET /oauth/login - 重定向到 Synapse OAuth2 登录页面
GET /oauth/callback - 处理来自 Synapse 的 OAuth2 回调

示例

验证

您需要使用真实的 Synapse 凭据进行身份验证才能使用服务器：

import requests

# Authenticate with Synapse
response = requests.post("http://127.0.0.1:9000/tools/authenticate", json={
 "email": "your-synapse-email@example.com",
 "password": "your-synapse-password"
})
result = response.json()
print(result)

# Alternatively, you can authenticate with an API key
response = requests.post("http://127.0.0.1:9000/tools/authenticate", json={
 "api_key": "your-synapse-api-key"
})

OAuth2 身份验证

1. 重定向流程（基于浏览器）

将用户定向到 OAuth 登录 URL：

http://127.0.0.1:9000/oauth/login?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI

2. 基于 API 的流程

对于程序化使用，首先获取授权URL：

import requests

# Get OAuth2 authorization URL
response = requests.post("http://127.0.0.1:9000/tools/get_oauth_url", json={
 "client_id": "YOUR_CLIENT_ID",
 "redirect_uri": "YOUR_REDIRECT_URI"
})
auth_url = response.json()["auth_url"]
# Redirect user to auth_url

获取实体

import requests

# Get an entity by ID
response = requests.get("http://127.0.0.1:9000/resources/entity/syn123456") # Replace with a real Synapse ID
entity = response.json()
print(entity)

获取实体注释

import requests

# Get annotations for an entity
response = requests.get("http://127.0.0.1:9000/resources/entity/syn123456/annotations") # Replace with a real Synapse ID
annotations = response.json()
print(annotations)

查询实体

import requests

# Query for files in a project
response = requests.get("http://127.0.0.1:9000/resources/query/entities/parent/syn123456", params={ # Replace with a real Synapse ID
 "entity_type": "file"
})
files = response.json()
print(files)

查询表

import requests

# Query a table
table_id = "syn123456" # Replace with a real Synapse table ID
query = "SELECT * FROM syn123456 LIMIT 10" # Replace with a real Synapse table ID
response = requests.get(f"http://127.0.0.1:9000/resources/query/table/{table_id}/{query}")
table_data = response.json()
print(table_data)

获取 Croissant 格式的数据集

import requests
import json

# Get public datasets in Croissant format
response = requests.get("http://127.0.0.1:9000/resources/croissant/datasets")
croissant_data = response.json()

# Save to file
with open("croissant_metadata.json", "w") as f:
 json.dump(croissant_data, f, indent=2)

部署

Docker

您可以使用 Docker 构建并运行服务器：

# Build the Docker image
docker build -t synapse-mcp .

# Run the container
docker run -p 9000:9000 -e SYNAPSE_OAUTH_CLIENT_ID=your_client_id -e SYNAPSE_OAUTH_CLIENT_SECRET=your_client_secret -e SYNAPSE_OAUTH_REDIRECT_URI=your_redirect_uri synapse-mcp
docker run -p 9000:9000 -e MCP_TRANSPORT=sse -e MCP_SERVER_URL=mcp://your-domain:9000 synapse-mcp

Fly.io

部署到 fly.io：

# Install flyctl
curl -L https://fly.io/install.sh | sh

# Login to fly.io
flyctl auth login

# Launch the app
flyctl launch

# Set OAuth2 secrets
flyctl secrets set SYNAPSE_OAUTH_CLIENT_ID=your_client_id
flyctl secrets set SYNAPSE_OAUTH_CLIENT_SECRET=your_client_secret
flyctl secrets set SYNAPSE_OAUTH_REDIRECT_URI=https://your-app-name.fly.dev/oauth/callback
flyctl secrets set MCP_TRANSPORT=sse
flyctl secrets set MCP_SERVER_URL=mcp://your-app-name.fly.dev:9000

# Deploy
flyctl deploy

与 Claude Desktop 集成

您可以将此 Synapse MCP 服务器与 Claude Desktop 集成，以使 Claude 能够在您的对话中直接访问和使用 Synapse 数据。

设置说明

首先，克隆存储库并安装要求：

# Clone the repository
git clone https://github.com/susheel/synapse-mcp.git
cd synapse-mcp

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

# Install dependencies
pip install -e .

配置 Claude Desktop 以使用 Synapse MCP 服务器：
- 打开 Claude 桌面
- 点击 Claude 菜单并选择“设置...”
- 点击左侧栏中的“开发者”
- 点击“编辑配置”
- 将以下配置添加到mcpServers部分：

"synapse-mcp": {
 "command": "python",
 "args": [
 "/path/to/synapse-mcp/server.py",
 "--host", "127.0.0.1",
 "--port", "9000"
 ]
}

保存配置文件并重新启动Claude Desktop
您现在可以在与 Claude 的对话中使用 Synapse 数据。例如：
- “从 Synapse 获取 ID 为 syn123456 的实体”
- “查询Synapse项目syn123456中的所有文件”
- “获取 Synapse 实体 syn123456 的注释”

贡献

欢迎贡献代码！欢迎提交 Pull 请求。

执照

麻省理工学院

Install Server

license - permissive license

quality

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Issues opened vs closed

Resources

GitHub Repository

Need Help?

Related Servers

Tools

Latest Blog Posts

Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
open source
OpenAI
Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security

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/susheel/synapse-mcp'

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

URL: https://glama.ai/mcp/servers/susheel/synapse-mcp?locale=zh-CN