Skip to main content
Glama
Synapse MCP Server

Synapse MCP Server

by susheel

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 つの認証方法をサポートしています。

  1. 認証トークン: Synapse認証トークンを使用して認証する

  2. OAuth2 : SynapseのOAuth2サーバーを使用して認証する

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 を使用してサーバーを構築および実行できます。

# 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 deploy

Claude Desktopとの統合

この Synapse MCP サーバーを Claude Desktop と統合すると、Claude が会話の中で Synapse データに直接アクセスして操作できるようになります。

セットアップ手順

  1. まず、リポジトリのクローンを作成し、要件をインストールします。

# 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 .
  1. Synapse MCP サーバーを使用するように Claude Desktop を構成します。

    • クロードデスクトップを開く

    • Claude メニューをクリックし、「設定...」を選択します。

    • 左側のバーにある「開発者」をクリックします

    • 「設定の編集」をクリックします

    • mcpServersセクションに次の構成を追加します。

"synapse-mcp": {
  "command": "python",
  "args": [
    "/path/to/synapse-mcp/server.py",
    "--host", "127.0.0.1",
    "--port", "9000"
  ]
}
  1. 設定ファイルを保存し、Claude Desktopを再起動します。

  2. クロードとの会話でSynapseデータを使用できるようになりました。例えば:

    • 「SynapseからID syn123456のエンティティを取得する」

    • 「Synapse プロジェクト syn123456 内のすべてのファイルをクエリする」

    • 「Synapseエンティティsyn123456の注釈を取得する」

貢献

貢献を歓迎します!お気軽にプルリクエストを送信してください。

ライセンス

マサチューセッツ工科大学

Available Tools

7 tools
get_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

    C2.9/5.0

    Scored across 7 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers