Synapse MCP Server
Synapse MCP サーバー
Synapse エンティティ (データセット、プロジェクト、フォルダー、ファイル、テーブル) を注釈とともに公開し、OAuth2 認証をサポートするモデル コンテキスト プロトコル (MCP) サーバー。
概要
このサーバーは、モデルコンテキストプロトコル(MCP)を介してSynapseエンティティとそのアノテーションにアクセスするためのRESTful APIを提供します。これにより、以下のことが可能になります。
Synapseで認証する
IDでエンティティを取得する
名前でエンティティを取得する
エンティティの注釈を取得する
エンティティの子を取得する
さまざまな基準に基づいてエンティティをクエリする
Synapseテーブルのクエリ
Croissant メタデータ形式でデータセットを取得する
Related MCP server: Reactome MCP Server
インストール
# 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: クラウド展開に Server-Sent Events を使用する
MCP_SERVER_URL: サーバーの公開URL (デフォルト: mcp://127.0.0.1:9000)OAuth2リダイレクトとサーバー情報に使用されます
サーバーは次の 2 つの認証方法をサポートしています。
認証トークン: 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_URI2. 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 を使用してサーバーを構築および実行できます。
# 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 にデプロイします。
# 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 deployClaude 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 .Synapse MCP サーバーを使用するように Claude Desktop を構成します。
クロードデスクトップを開く
Claude メニューをクリックし、「設定...」を選択します。
左側のバーにある「開発者」をクリックします
「設定の編集」をクリックします
mcpServersセクションに次の構成を追加します。
"synapse-mcp": {
"command": "python",
"args": [
"/path/to/synapse-mcp/server.py",
"--host", "127.0.0.1",
"--port", "9000"
]
}設定ファイルを保存し、Claude Desktopを再起動します。
クロードとの会話でSynapseデータを使用できるようになりました。例えば:
「SynapseからID syn123456のエンティティを取得する」
「Synapse プロジェクト syn123456 内のすべてのファイルをクエリする」
「Synapseエンティティsyn123456の注釈を取得する」
貢献
貢献を歓迎します!お気軽にプルリクエストを送信してください。
ライセンス
マサチューセッツ工科大学
Available Tools
7 toolsget_datasets_as_croissantB
Get public datasets in Croissant metadata format.
Inputs: no named parameters. Returns: object
get_entityB
Get a Synapse entity by ID.
Inputs: entity_id (required). Returns: object
get_entity_annotationsC
Get annotations for an entity.
Inputs: entity_id (required). Returns: object
get_entity_childrenB
Get child entities of a container entity.
Inputs: entity_id (required). Returns: result
query_entitiesD
Query entities based on various criteria.
Inputs: annotations, entity_type, name, parent_id. Returns: result
query_tableC
Query a Synapse table.
Inputs: query (required), table_id (required). Returns: object
search_entitiesC
Search for Synapse entities.
Inputs: search_term (required), entity_type, parent_id. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Most tools have distinct purposes targeting different Synapse operations, but query_entities and search_entities could cause some confusion as both involve finding entities. The descriptions help differentiate them, with query_entities focusing on structured criteria and search_entities on broader search, but overlap exists.
Tool names follow a highly consistent verb_noun pattern throughout, using snake_case uniformly. All tools start with a clear verb (get, query, search) followed by a specific noun, making them predictable and easy to understand.
With 7 tools, this server is well-scoped for interacting with Synapse entities and datasets. Each tool serves a distinct function in the domain, such as retrieving entities, annotations, children, datasets, and querying/searching, without being overly sparse or bloated.
The tool set covers core read and query operations for Synapse entities and datasets effectively, including retrieval, annotation access, and searching. A minor gap exists in write operations (e.g., create, update, delete entities), but agents can likely work around this for many use cases.
Maintenance
Related MCP Connectors
Model Context Protocol server for Studex tools, notifications, and profile integrations
Siftable MCP server for governed work, knowledge, calendar, people, datasets, and Vault.
OAuth-protected, read-only-by-default MCP server for provenance-labeled QuillCaddie project memory.
MCP server for the GDEX (Geoscience Data Exchange) data portal: datasets, files, metrics, subsetting
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA server implementation of the Model Context Protocol (MCP) that provides REST API endpoints for managing and interacting with MCP resources.-
- AlicenseAqualityDmaintenanceModel Context Protocol server for accessing Reactome pathway and systems biology data.812MIT
- AlicenseBqualityDmaintenanceA production-ready Model Context Protocol (MCP) server that provides comprehensive access to the BioOntology API for searching, annotating, and exploring over 1,200 biological ontologies.1010MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that wraps the Accela Construct API as a curated, capability-grouped tool set for Accela Civic Platform, safe by default with read-only access.94 PyPI1Apache 2.0