Biolab MCP Server

Biolab MCP Server

「AI エージェントが生物学データベースを検索しても、監査証跡は残りません。半年後には、誰もこうした質問に答えられません。この結果を返した正確なクエリは何だったのか、いつ実行されたのか、その時点でその論文は査読済みだったのか。Biolab がそれを解決します。」

Python と Go のクライアントを備えた、ローカルファーストの科学的エビデンスワークスペースです。科学者や AI エージェントと、PubMed、Europe PMC、ClinicalTrials.gov、UniProt、Open Targets、bioRxiv/medRxiv の間に位置します。取得のたびにソースの応答を保存し、retrieval_id を返します。プロジェクト、レビュー済みコレクション、エビデンスの監視、主張とのリンクによって、その上に追跡可能なワークフローを構築します。

MCP を初めて使いますか？ MCP は、AI アシスタント（Codex、 ChatGPT、Claude、Cursor など）が会話中に外部ツールを呼び出せるようにするオープン標準です。 Biolab を追加すると、アシスタントは科学的エビデンスを取得、保存、整理、監視、引用できるようになり、 後からすべての結果を検証できます。

今すぐ使う — インストール不要

ホストインスタンスを https://srikarjy025-biolab-mcp.hf.space/mcp で利用できます。クライアントの接続先に指定すれば準備完了です。ホスト版の機能は、現在デプロイされているバージョンに準じます。このリポジトリにある完全な 0.4 ワークスペースを使うには、ローカルで実行してください。

Claude Code:

claude mcp add --transport http biolab https://srikarjy025-biolab-mcp.hf.space/mcp

Claude Desktop / Cursor — MCP 設定ファイルに以下を追加します。

{
  "mcpServers": {
    "biolab": {
      "url": "https://srikarjy025-biolab-mcp.hf.space/mcp"
    }
  }
}

（キーを取得したら、"url" と同じ階層に "headers": {"Authorization": "Bearer <your key>"} を追加してください。下記のレート制限に関する注記をご覧ください。）

0.4 サーバーは、統合検索、ソース別検索、標準の search／fetch、取得内容の確認、プロジェクト、コレクション、監視、主張、レポートを提供します。取得のたびにハッシュチェーン型の監査証跡に記録され、後から確認できます（下記の監査証跡スキーマをご覧ください）。

複数のソースを横断した調査には、search_evidence を使うと、1 回の呼び出しで PubMed、Europe PMC、 ClinicalTrials.gov、UniProt、Open Targets を検索できます。 各ソースの結果とエラーも明示的に保持されます。

公式 MCP Registry と Smithery にも掲載されています。そちらから見つけてインストールすることもできます。

レート制限に関する注記。 ホストサーバーは共有で常時利用可能で、気軽に使う場合は登録不要です。ただし、API キーを持たない利用者は、少量でスループットの低い共通枠（PubMed は 1 req/s）を共有します。匿名ユーザーがほかの利用者の利用を妨げないようにするためです。数回を超えるクエリを実行する場合は、下記の方法でキーを申請してください。独立した、より大きな利用枠を利用できます。

キーの取得方法:

Authorization: Bearer <your key>

クライアントの MCP 設定にこのヘッダーを追加してください（Claude Code の場合：claude mcp add --transport http biolab <url> --header "Authorization: Bearer <key>"）。キーは biolab keys create <label> で発行できます。独自のインスタンスを実行している場合は、下記のAPI キーの管理をご覧ください。それ以外の場合は、メンテナーにキーを依頼してください。

独自のコピー（ローカル開発、独自のストレージ、セルフホスト）を実行したい場合は、このまま読み進めてください。

問題

創薬チームが、遺伝子標的を調査するために AI エージェントを使用しています。エージェントは 3 日間で PubMed を 200 回検索し、膵臓がんで遺伝子 X が上方制御されていると主張する論文を提示しました。ある研究者はそれに基づいて判断を下しました。6 か月後、FDA への申請時に、次の疑問が生じます。

• その論文が返された正確なクエリは何ですか？
• 取得日はいつですか？
• 取得時点ですでに査読済みでしたか、それとも後日公開されたプレプリントでしたか？
• エージェントは正確に要約しましたか、それとも詳細を幻覚しましたか？

Biolab がなければ、これらの疑問に答えられる人はいません。取得の過程は見えないままです。

Biolab の機能

Biolab は取得レイヤーではなく、傍受とログ記録のレイヤーです。エビデンスを解釈したり、順位付けしたり、要約したりすることはありません。エージェントの主張を常に改ざん不可能な原本まで追跡できるよう、起きたことをそのまま記録します。

Your AI Agent
    ↓  MCP tool call (e.g. search_pubmed)
Biolab MCP Server
    ↓  HTTP
Source API (PubMed, Europe PMC, ClinicalTrials.gov, bioRxiv/medRxiv)
    ↓  paper
Biolab writes a hash-chained retrieval record to the audit database
    ↓  paper + retrieval_id
Back to your agent

エージェントは要求した論文を取得します。Biolab は、実際に起きたことを正確に記録した、永続的でクエリ可能な改ざん検知機能付きの記録を保持します。

対応ソース

ソース	MCP ツール	CLI コマンド	備考
PubMed	search_pubmed	biolab search	E-utilities、完全な XML を保存
Europe PMC	search_europepmc	biolab search-europepmc	無料、bioRxiv/medRxiv をインデックス化
ClinicalTrials.gov	search_clinicaltrials	biolab search-clinicaltrials	API v2、条件ベースの検索
UniProt	search_evidence	biolab evidence	タンパク質のレコードと配列
Open Targets	search_evidence	biolab evidence	GraphQL を介した標的、疾患、薬剤のエンティティ
bioRxiv/medRxiv	search_biorxiv	biolab search-biorxiv	日付範囲によるページネーション（API の制限）

すべてのソースは、ソースに依存しない単一のスキーマを使う単一の監査データベース（ローカルでは SQLite、本番環境では Turso — ホスト型の SQLite 互換データベース）を共有します。

自分でビルドする

ローカル環境で実行するのに Python や Go の知識は必要ありません。以下の手順を順番に進めてください。すべてのコマンドはターミナルで実行します。

前提条件

• Python 3.11 以降 — python3 --version で確認してください。インストールされていない場合は、python.org から入手してください。
• Git — コードのダウンロード（クローン）に使います。git --version で確認してください。

Python を使う手順で必要なのは本当にこれだけです。インストールするデータベースサーバーはなく、API キーも必要ありません（PubMed は匿名で利用できますが、レート制限は低くなります）。

1. コードを取得する

git clone https://github.com/srikarjy/biolab-mcp-server.git
cd biolab-mcp-server

2. インストールする

python3 -m venv .venv          # creates an isolated Python environment
source .venv/bin/activate      # on Windows: .venv\Scripts\activate
pip install -e ".[dev]"        # installs the package + test tools
# Add the optional remote Turso driver only if needed: pip install -e ".[turso]"

3. 試してみる

biolab demo --query "BRCA1 pancreatic cancer"

この操作では PubMed を実際に検索し、すべての結果をローカルの biolab.db ファイルに保存します（自動的に作成されるため、セットアップは不要です）。また、各論文の retrieval_id を出力します。これは AI エージェントが MCP 経由で受け取るものと同じ ID です。

4. テストスイートを実行する（任意、すべてが動作することを確認します）

pytest -m "not live and not benchmark" -v

ネットワークアクセスとローカルソケットのバインドが利用できる場合は、pytest -m live -v を別途実行してください。これらのテストでは、PubMed、Europe PMC、ClinicalTrials.gov、bioRxiv の実際のサービスを使用します。デフォルトのコマンドは、決定的にオフラインで実行されます。

5. MCP サーバーとして実行する（AI エージェントが実際に接続する方法）

python -m biolab.server

これにより、http://localhost:8000/mcp で HTTP サーバーが起動します。今すぐ利用すると同じように、Claude Desktop、Claude Code、または Cursor からこの URL に接続してください。ホストされた URL の代わりに localhost:8000 を使います。

6. Docker イメージをビルドする（任意）

ローカルに Python をインストールしたくない場合は、次の方法を使えます。

docker build -f space/Dockerfile -t biolab-mcp .
docker run -p 8000:8000 biolab-mcp

（TURSO_DATABASE_URL/TURSO_AUTH_TOKEN を設定しない場合、ストレージにはコンテナ内の一時ファイルがデフォルトで使用されます。詳しくは、以下の環境変数を参照してください。）

ビルド済みリリースを使いますか？

pipx install biolab-mcp      # or: pip install biolab-mcp

# Or the Go binary, no Python required at all:
curl -L https://github.com/srikarjy/biolab-mcp-server/releases/latest/download/biolab_darwin_arm64.tar.gz | tar xz
./biolab search "BRCA1 pancreatic cancer" --max 3

使用方法

CLI（科学者向け）

# Search several evidence sources in one audited workflow
biolab evidence "KRAS pancreatic cancer" \
  --sources pubmed,europepmc,clinicaltrials,uniprot,opentargets --max 5

# Search PubMed
biolab search "BRCA1 pancreatic cancer" --max 5

# Search Europe PMC
biolab search-europepmc "BRCA1 pancreatic cancer" --max 5

# Search ClinicalTrials.gov
biolab search-clinicaltrials "pancreatic cancer" --max 5

# List bioRxiv preprints (no free-text search - API limitation)
biolab search-biorxiv neuroscience --max 10
biolab search-biorxiv all --server medrxiv --max 10

# Retrieve full audit record
biolab get <retrieval_id>

# List recent retrievals
biolab list --source pubmed --limit 10

# Export for analysis
biolab export evidence.jsonl --source clinicaltrials

# Verify the complete tamper-evident audit chain
biolab verify --db biolab.db

# Run demo
biolab demo --query "BRCA1 pancreatic cancer"

# Run the offline portfolio demo (no network or scientific claims)
biolab portfolio-demo

# Run the real end-to-end scientist workflow against a local server
python scripts/scientist_workflow_demo.py --url http://127.0.0.1:8000

# Start the private local dashboard and REST API
biolab web
# Open http://127.0.0.1:8000

# Create a project, organize evidence, and trace a claim
biolab projects create "KRAS target review" --description "Pancreatic cancer evidence"
biolab collections create <project_id> "Reviewed evidence"
biolab collections add <collection_id> <retrieval_id> --relevance relevant --note "Reviewed"
biolab claims create <project_id> "KRAS is a therapeutic target"
biolab claims link <claim_id> <retrieval_id> --stance supports --assessment human_reviewed

# Monitor a source for added, removed, or revised records
biolab watches create <project_id> pubmed "KRAS pancreatic cancer"
biolab watches run-all

# Export a complete project report
biolab projects report <project_id> --output report.md

ダッシュボードはデフォルトで 127.0.0.1 にバインドされます。REST エンドポイントでは、エビデンス、 プロジェクト、コレクション、監視、主張、レポートを扱えます。/openapi.json でエンドポイントを確認できます。 運用には /health、/metrics、/v1/verify を使用してください。リモートに公開する前に、 biolab keys create で作成したキーを使って biolab web --require-auth を実行するか、 統合 MCP サーバーで BIOLAB_REQUIRE_AUTH=true を設定してください。

MCP ツール（エージェント向け）

// Search any source
{"name": "search_evidence", "arguments": {"query": "KRAS pancreatic cancer", "agent_id": "research:target-validation", "sources": ["pubmed", "europepmc", "clinicaltrials", "uniprot", "opentargets"], "max_results": 5}}
{"name": "search_pubmed", "arguments": {"query": "BRCA1 pancreatic cancer", "agent_id": "aletheia:advocate", "max_results": 5}}
{"name": "search_europepmc", "arguments": {"query": "BRCA1 pancreatic cancer", "agent_id": "aletheia:advocate", "max_results": 5}}
{"name": "search_clinicaltrials", "arguments": {"query": "pancreatic cancer", "agent_id": "aletheia:advocate", "max_results": 5}}
{"name": "search_biorxiv", "arguments": {"category": "neuroscience", "agent_id": "aletheia:advocate", "max_results": 5, "server": "biorxiv"}}

// Retrieve full audit record (works for ALL sources)
{"name": "get_retrieval", "arguments": {"retrieval_id": "uuid-from-search"}}

BioClaw

すぐにコピーして使える BioClaw スキルが integrations/bioclaw/biolab-evidence に含まれています。BioClaw のコンテナ化された リサーチアシスタントをローカル REST API に接続し、追加の Python パッケージなしで、 複数ソースの検索、取得内容の確認、チェーンの検証に対応します。

Codex と ChatGPT

• python -m biolab.server でローカルサーバー全体を起動します。
• integrations/codex/config.toml.example を Codex の設定にコピーし、 開発中はツールの承認を prompt に設定しておきます。
• ポータブルなエージェントプラグインのバンドルは plugins/biolab/ にあります （plugin.json、mcp.json、エビデンスワークスペーススキル）。公開または提出する前に、 mcp.json のリモート URL を HTTPS のデプロイ先に変更してください。
• MCP サーバーには、標準のナレッジツールである search と fetch に加え、 より高機能な Biolab ツールが含まれています。ツールのアノテーションにより、読み取り専用、 書き込み、外部データ、冪等性の動作がクライアントに開示されます。

そのため、ChatGPT/Codex はエビデンスを検索して保持し、プロジェクトの状態を作成し、 監視を実行し、主張をたどることができます。アシスタントは関係性を提案しますが、 実際に関係性をレビューした場合は、科学者が human_reviewed を使用する必要があります。

REST と API ゲートウェイ

python -m biolab.server の単一プロセスで、/mcp の MCP、/ のダッシュボード、 /v1 配下の REST を提供します。主なルートは次のとおりです。

ルート	用途
POST /v1/evidence/search	監査可能な複数ソース検索
GET /v1/retrievals/{id}	保持された取得内容の全体
GET, POST /v1/projects	プロジェクトの一覧表示または作成
POST /v1/collections	レビュー済みコレクションの作成
GET, POST /v1/watches	監視クエリの一覧表示または作成
POST /v1/watches/run-all	スケジュールに基づくドリフト検出
POST /v1/claims	真実であると断定せずに主張を作成
GET /v1/claims/{id}	主張とエビデンスの関係をたどる
GET /v1/projects/{id}/report	JSON または ?format=markdown 形式のレポート
GET /openapi.json	ゲートウェイ/API の検出ドキュメント

deploy/gateway/ にある無料の Caddy/Docker の例では、リバースプロキシ境界と永続ボリュームを追加します。 デフォルトでは localhost のみにバインドされます。一般公開する前に、実ドメイン、HTTPS、バックアップ、 組織固有の認可を設定してください。

Python API

from biolab.pubmed_client import search_and_fetch
from biolab.retrieval_log import write_retrieval, get_retrieval
from biolab.db import connect

conn = connect("biolab.db")
papers = search_and_fetch("BRCA1 pancreatic cancer", 3)
for p in papers:
    record = write_retrieval(conn, query="...", pmid=p.pmid, ...)
    print(record.retrieval_id)

API キーの管理

サーバーは設計上、認証されていない呼び出し元にも開放されています。ただし、呼び出し元は全員、 小規模でスループットの低いレート制限枠を共有します（今すぐ使うを参照）。 キーを発行すると、そのユーザー専用の、より大きな枠が割り当てられます。これは アクセス を制限するものではなく、 PubMed の実際のレート制限に対する他のユーザーの枠を、1 人の呼び出し元が使い切らないようにするための、 公平性を保つ仕組みです。

# Issue a key — the raw key is shown once, save it immediately
biolab keys create alice

# List issued keys (never shows the raw key — only a hash is stored)
biolab keys list

# Revoke all of a label's active keys
biolab keys revoke alice

呼び出し元はキーを Authorization: Bearer <key> として送信します。デフォルトでは、 ヘッダーがない場合は匿名ユーザー用の枠が使われ、無効または失効したキーの場合は 401 が返されます。 キーのないリクエストも拒否するには、BIOLAB_REQUIRE_AUTH=true を設定してください。

環境変数

すべて任意です。何も設定しなくても、サーバーは適切なデフォルト値で動作します。

変数	目的	デフォルト
BIOLAB_DB_PATH	ローカルの SQLite ファイルパス（TURSO_DATABASE_URL が設定されている場合は無視されます）	biolab.db
TURSO_DATABASE_URL	任意のリモート Turso URL。pip install "biolab-mcp[turso]" が必要です	未設定（ローカルファイルを使用）
TURSO_AUTH_TOKEN	上記の Turso データベースの認証トークン	未設定
BIOLAB_HOST	MCP サーバーがバインドするホスト。ループバック以外を指定するには、BIOLAB_REQUIRE_AUTH=true または BIOLAB_ALLOW_ANONYMOUS=true が必要です	127.0.0.1
BIOLAB_PORT	MCP サーバーがリッスンするポート	8000
BIOLAB_REQUIRE_AUTH	MCP／REST リクエストに有効な Bearer API キーを必須にします	false
NCBI_API_KEY	PubMed のレート制限を 3 req/s から 10 req/s に引き上げます	未設定（なくても問題なく動作します）

監査証跡スキーマ（v2）

CREATE TABLE retrievals (
    retrieval_id     TEXT PRIMARY KEY,  -- UUID
    source           TEXT NOT NULL,     -- pubmed, europepmc, trials, UniProt, Open Targets, etc.
    external_id      TEXT NOT NULL,     -- PMID, NCT ID, DOI, etc.
    query_text       TEXT NOT NULL,     -- exact query sent to source
    retrieved_at     TEXT NOT NULL,     -- ISO 8601 UTC
    agent_id         TEXT NOT NULL,     -- e.g. "aletheia:advocate"
    source_metadata  TEXT NOT NULL,     -- JSON: source-specific fields
    raw_response     TEXT NOT NULL,     -- verbatim XML/JSON from source
    snapshot         TEXT NOT NULL,     -- JSON: structured fields (title, abstract, authors, journal, DOI, pub types, MeSH/conditions)
    response_hash    TEXT NOT NULL,     -- SHA-256(prev_hash + raw_response + retrieval_id + retrieved_at)
    prev_hash        TEXT NOT NULL      -- response_hash of the previous row — makes this a hash chain
);

主な特性：

• 論文の取得ごとに 1 行（クエリごとではありません）
• 生のレスポンスをそのまま保存するため、解析のバグから復旧できます
• ハッシュチェーンを使用します。単にハッシュ化するだけではありません。各行のハッシュには前の行のハッシュも含まれるため、データベースを直接操作した場合も含め、行を削除または編集すると、その後のすべての行でチェーンが破損します。retrieval_log.verify_chain(conn) を呼び出すとログ全体を確認でき、破損があれば該当する行を正確に返します。
• バックグラウンド書き込みキューですべての書き込みを 1 つの経路に集約するため、エージェントからの呼び出しが同時に行われてもチェーンの整合性が保たれます

改ざん検知と実行ランタイム

• 取得行は監査対象のすべての列を対象にハッシュチェーン化されます（hash_version 2）。従来の v1 行も検証できます。
• biolab anchor out.json [--chain retrievals|executions] は、チェーンの先頭の HMAC 署名付きチェックポイントを作成します（BIOLAB_ANCHOR_KEY）。データベースホストの外部に保管してください。その後 biolab verify-anchor out.json を実行すると、チェーンだけでは検出できない末尾の切り詰めや全面的な書き換えも検知できます。
• biolab run-tool <tool> -i '{...}' は登録済みツール（sequence_stats、mmseqs が PATH にある場合は mmseqs2_search）を実行し、コンテンツアドレス指定されたアーティファクトを含む不変の ExecutionRecord を封印します。biolab executions {list,show,verify,replay,artifact} で検査、検証、再実行を行えます。レコードを封印できない場合、結果は返されません。
• Go 版（go-biolab/）も同じ v2 チェーンを書き込み、verify、anchor、verify-anchor を備えています。ハッシュは Python 版とバイト単位で互換性があり、共有テストベクトルで固定されています。Go 版には実行ランタイムは実装されていません。

アーキテクチャ

biolab/
├── cli.py                   # Search plus scientist workspace commands
├── server.py                # Unified MCP + REST + dashboard process
├── evidence.py              # Shared multi-source orchestration and audit persistence
├── workspace.py             # Projects, collections, watches, claims, reports
├── web.py                   # Local dashboard + versioned REST API
├── db.py                    # Connection + schema (local SQLite or remote Turso)
├── models.py                 # RetrievalRecord dataclass
├── retrieval_log.py          # Only writer + background queue + hash chain
├── pubmed_client.py           # PubMed E-utilities wrapper + rate limiter
├── europepmc_client.py        # Europe PMC adapter
├── clinicaltrials_client.py   # ClinicalTrials.gov adapter
├── uniprot_client.py          # UniProt adapter
├── opentargets_client.py      # Open Targets GraphQL adapter
├── biorxiv_client.py          # bioRxiv/medRxiv adapter
└── migrations/                # Schema migration scripts

integrations/
├── bioclaw/                   # BioClaw evidence skill and REST client
└── codex/                     # Local MCP configuration template

plugins/biolab/                # Portable Codex/ChatGPT Agent Plugin bundle
deploy/gateway/                # Caddy + Docker Compose deployment template

space/                      # Files pushed to the hosted Hugging Face Space
├── Dockerfile                # Python-server-specific image (see repo-root Dockerfile for the Go one)
└── README.md                  # Space config (title, hosting metadata)

設計原則：

• Python と Go による実装（インターフェースは共通、ランタイムは別）
• CLI、MCP、REST、Web の各提供方法で共有するコア
• ログファイルではなくデータベースを使用し、時間をまたいだ構造化クエリを可能にします
• フェイル時は必ずエラーにし、機能を劣化させません。retrieval_id のない論文はエラーよりも悪い状態です
• オフライン受け入れテストと、明示的なライブコネクターテスト
• 行レベルのロックではなく単一書き込みキューを使用し、同時実行時にハッシュチェーンの整合性を保つ最もシンプルな方法を採用します

開発

# Python
pip install -e ".[dev]"
pytest -m "not live and not benchmark" -v

# Go
cd go-biolab
go test ./...
go build -o biolab ./cmd/cli
go build -o biolab-server ./cmd/server

デプロイ

ターゲット	方法
ホスト型（インストール不要）	https://srikarjy025-biolab-mcp.hf.space/mcp — 機能はデプロイされている Space のバージョンによって異なります
ローカル	pipx install biolab-mcp またはバイナリをダウンロード
CI/CD	GitHub Actions → PyPI（Trusted Publishing／OIDC）＋ GHCR ＋ GitHub Releases
コンテナ	docker pull ghcr.io/srikarjy/biolab-mcp:latest、または space/Dockerfile を使って自分でビルド
Linux パッケージ	goreleaser を使用した .deb、.rpm、.apk
ディスカバリー	MCP Registry · Smithery

学生向けの低コストな方法： ローカルの SQLite、CLI、ダッシュボード、MCP サーバー、BioClaw クライアント、Caddy ゲートウェイは、有料サービスを必要としません。無料のホスト型プランも利用できる場合がありますが、クォータや永続化ポリシーは変更される可能性があるため、パブリックデプロイに依存する前に確認してください。

ロードマップ

• レスポンスハッシュによるエビデンスの追加・削除・内容変更の監視
• プロジェクト、コレクション、主張、レポート、REST、ダッシュボード、エージェントのパッケージ化
• 来歴グラフ（DOI によるソース間のリンク）
• Nextflow／Snakemake プラグイン
• レート制限とキャッシュ（監査に対応）
• 組織アカウントとプロジェクト単位の詳細な認可
• 確実なアラート配信を備えた撤回・訂正フィード

ライセンス

MIT — LICENSE を参照してください

作者

Srikar Jy — [email protected]