openalex-mcp-server

---

概要

OpenAlex の学術カタログデータを利用できます。2億7,000万件以上の著作物、9,000万人以上の著者、10万件以上の情報源に加え、機関、トピック、キーワード、出版社、資金提供者のデータを収録しています。8 種類すべてのエンティティを検索、絞り込み、集計し、曖昧な名称を正式な ID に解決したり、引用グラフを 1 ホップずつたどったりできます。

ツール

ツール	説明
openalex_search_entities	8 種類すべてのエンティティを対象に、検索、絞り込み、並べ替え、または ID による取得を行います
openalex_analyze_trends	トレンドや分布の分析に使用するグループ化集計を行います
openalex_resolve_name	名称または識別子（DOI、ORCID、ROR、PMID、ISSN、OpenAlex ID）を OpenAlex ID に解決します
openalex_get_citation_graph	起点となる著作物から引用グラフを 1 ホップたどります。cites、cited_by、または related_to を指定できます
openalex_describe_fields	エンティティ種別で有効なフィルター、group_by、select のフィールド名を一覧表示します

プロンプト

プロンプト	説明
openalex_literature_review	系統的な文献検索をガイドします。クエリの作成、検索、絞り込み、引用ネットワークの分析、知見の統合を行います
openalex_research_landscape	トピックの研究状況を分析します。研究量の推移、主要な著者・機関、オープンアクセス率、資金源を調べます

機能リファレンス

openalex_search_entities _ツール

• IDで単一のエンティティを取得します — OpenAlex ID、DOI、ORCID、ROR、PMID、ISSN、PMCID（裸の値またはURL形式。https://openalex.org/works/W2741809807 などのOpenAlexレコードページURLやAPI URLを含む）、またはスラッグやキーワードURLで指定したキーワードです。entity_type: "funders" では、資金提供者のCrossref Funder Registry DOI（10.13039/…）は、1件を返すリストリクエストで解決されます。OpenAlexはIDによる検索に課金しません。ただし、次の3つの場合はリスト呼び出し1回分として課金されます。スラッグまたはURLで検索したキーワード、識別子の後ろに文字が続くid（W2741809807#xでもW2741809807を返します）、および資金提供者のDOIリクエストです。idが優先されます。これと一緒に渡された検索パラメーターは破棄され、レスポンスにその内容が示されます。entity_typeと異なる種類のエンティティを示す文字で始まるOpenAlex IDは、上流への呼び出し前にid_type_mismatchとして失敗します。また、.または..のパスセグメントを含むidは、通常形式でもパーセントエンコード形式でもid_dot_segmentとして失敗します。識別子内の?、#、\、タブ、改行は、その一部としてパーセントエンコードされて送信されます（SICI DOIは#で終わります）。PMCIDでは何も解決されません（OpenAlexにはインデックスされていません）。代わりに該当する著作物のPMIDまたはDOIを使用してください
• キーワード検索（ブール演算子、引用符で囲んだフレーズ、ワイルドカード、あいまい一致）と、exactおよびsemantic検索モード。semanticはクエリに応じた候補セットを約1 req/secでランク付けします（1ページあたり最大50件）。そのmeta.countは一致総数ではなく候補数を示します
• filtersには、レコードオブジェクト、または曖昧さのないネイティブ文字列（"issn:0920-8542"）を指定でき、filterエイリアス経由でも使用できます。変換内容はnoticeに記載されます。対応する二重引用符の外にあるカンマは節の区切りとなり、最初のコロンはキーと値の区切りとなります。DOIやURLのコロン、および引用符で囲まれたカンマを含むフレーズはそのまま保持されます。重複するキー、キーのない断片、閉じていない引用符は拒否され、レコード形式での指定方法が案内されます。レコードではキーごとに値を1つ指定します。同じ上流フィールドを指す別名は、それぞれAND条件として適用されます。レコードオブジェクトを必須にするにはOPENALEX_FILTER_STRING_INPUT=falseを設定します。ネイティブ文字列はこのツールのフィルターにのみ適用され、公開されているスキーマは引き続きレコード形式です
• 4つのフィルター対応ツールすべてで、引用符で囲まずに送信するフィルター値には、対応する二重引用符が必要です（unmatched_quote_in_filter_value）。引用フィルターはシード検索の前に検証されます。"graph neural" networksのような、引用符が正しく対応した検索フレーズは、.search.exactを含め、有効です。二重引用符で囲んで送信する値には、その中に二重引用符を含めることはできません（quote_in_filter_value）
• 詳細なフィルター構文：フィールド間はAND、フィールド内はOR（|）、フィールド内はAND（+）、NOT（!）、範囲、比較に対応します。1つの値に、|とAND演算子を併用することはできません。AND演算子は+、またはID、コード、languageキーで値の間に入れるスペースです（言語名の一部であるスペースはそのまま保持されます。また、国フィールドではスペースは常に国名の一部であり、AND演算子にはなりません。DE US|FRはinvalid_country_codeとして失敗します）。OpenAlexはまず値を|で分割し、複数の値をANDで結ぶ選択肢をすべて除外するため、DE|FR+USとauthorships.author.id: A1 A2|A3はいずれもリクエスト前にmixed_and_or_in_filter_valueとして失敗します。代わりにAND条件は別のキーに指定してください（著作物の場合は、institutions.country_code: USとauthorships.institutions.country_code: DE|FRを併記します）。フリーテキスト検索フィルター（.searchキー、つまりtitle.search、abstract.search.exact、title_abstract_keywords.search）またはOpenAlexが全文一致させるフィールド（以下に列挙）内のカンマは、フレーズの一部として二重引用符で囲んで送信されます。それ以外のフィルター値内のカンマはcomma_in_filter_valueとして失敗します（ORには|を使用してください）。.search値では、DOI、日付（タイムスタンプの+00:00オフセット）、URL（ブール値のhas_pdf_urlを除くlanding_page_url）、完全一致する名前（display_name、awards.funder_display_nameのC++、Erasmus+）、biblioフィールド（号を示す1+2）、またはawards.funder_award_id内の+は、文字として扱われます。OpenAlexが全文一致させるフィールド（display_name、awards.funder_display_name、awards.funder_award_id、geo.city、geo.region、raw_affiliation_strings、block_key、biblioフィールド）で値にスペースが含まれる場合は、1つのフレーズとして一致するよう二重引用符で囲んで送信されます（awards.funder_display_name: National Science Foundation）。これらのフィールドでは!と|は使用できます（geo.city: New York|Boston）が、+を使って同一フィールド内の別の値とAND条件にすることはできません。このような値にはカンマも含められます（raw_affiliation_strings: Associazione Meteonetwork OdV, Milano, Italy）。カンマを含む値は引用符で囲んで送信され、その中の+は文字として扱われます。この形式で引用符で囲んで送信する値の外側の引用符内に二重引用符が含まれる場合、またはフリーテキスト検索以外のフィルターで値を二重引用符で囲んだ場合、その内部に二重引用符が含まれるとquote_in_filter_valueとして失敗します
• 国と言語の値は、ここおよびfiltersを受け取るすべてのツールで、OpenAlexが保存するコードに変換されます。国フィールド（キーがcountry_code、country_codes、countriesのいずれかで終わるもの）では、ISO 3166-1 alpha-3コード、数値コード、英語名（ISOのもの、またはOpenAlex独自の国ファセットに表示されるもの（Russia、Ivory Coast、Trinidad & Tobago））がalpha-2コードに変換されます（DEU、276、Germany → DE）。また、UKはGBになります。国コードとして認識できない値（Germanyy、999、unknown、またはスペースでつないだ2つのコードであるDE US）は、フィルターの送信前にinvalid_country_codeとして失敗します。languageでは、ISO 639-2コードはISO 639-1コードに変換され、英語名はコードに変換されます（eng、English → en、Cebuano → ceb）。各|／+セグメントは個別にトリミングされ、変換されるため、複数語の名前も1つの値として扱われます（South Korea|Japan → KR|JP、Scottish Gaelic|English → gd|en）。それ以外（null、XK、ceb、zh-cn、countries/DEU形式のパス）は、指定されたとおりに送信されます
• selectは、別途指定されない限りエンティティタイプごとに定められたデフォルトを返します。全レコードを取得するには["*"]を指定します。無効なフィールド名を指定すると、有効なフィールドの一覧を含むエラーが返されます。著作物では、author_listは著者をオーサーシップ順に{id, display_name, orcid}として返します。機関や所属も含むauthorshipsの約10分の1のサイズで、デフォルトにも["*"]にも含まれません
• キーワード検索とexact検索では、カーソルページネーションを使用でき、1ページあたり最大100件です（デフォルトは25件）。semantic検索では、代わりにpage（1始まり）を使用して候補を順に取得します。誤ったsearch_modeとページ指定パラメーターを併用すると、上流への呼び出し前に拒否されます
• sample（最大100件、1ページのみ。cursorもpageも適用されません）と、再現可能なランダムサンプリングを行うための決定論的なseedを指定できます。keywordモードとexactモードのみで利用でき、sortとの併用はできません。OpenAlexはsemantic検索をサンプリングせず、ソート付きサンプルも拒否するため、どちらの組み合わせも上流への呼び出し前に拒否されます
• 各レスポンスのサイズは、各サーフェス（structuredContent、およびトレーラーを含むcontent[]）あたり64,000バイト以内です。ただし、返せる最小サイズがこれを超える場合は、over_budgetとして通知されます。ページが上限を超える場合、先頭のレコードは完全な形で保持され、残りはomittedに列挙されます。残りのレコードは、次の呼び出しで（まとめて、OpenAlexの順序で）取得でき、next_cursorには影響しません。単独でもサイズが大きすぎるレコードは、最大の配列をウィンドウ化して返します。各配列には、収まる分が順に格納され、配列のうちどれだけを保持しているかが示されます。ID検索のslice: {field, offset}では、配列の末尾までページ単位で取得できます
• リストレコードのauthorshipsまたはauthor_listがちょうど100件の場合、上限に達した可能性があることが通知されます。保存されている著者をさらに取得するには、idとsliceを指定して呼び出してください。単一エンティティの検索とスナップショットでは、各著作物につき最大5,000件のauthorshipsが保持されます。この上限に達した場合、すべてのスライスで両方の著者フィールドが上限に達した可能性があることが示されます。totalは完全な著者一覧ではなく、保存されている項目数を数えます。保存済みの項目をすべて取得するとnextはnullになります。この保存上限を超える著者は、OpenAlexからの再取得やスナップショットでも取得できません
• 検索／引用では100、分析では200を超える正の整数のper_page値は最大値に制限され、要求されたサイズと適用されたサイズがnotice、ログ、カウンターに記録されます。公開されている最大値を超える値の拒否に戻すには、OPENALEX_CLAMP_PER_PAGE=falseを設定します。0、負数、小数、semantic検索で50を超える値、上限を超えるサンプルは引き続き拒否されます。idを指定するとページサイズは無視され、sampleを指定するとページサイズは上書きされます
• タイトルのないレコードではdisplay_nameはnullになります。すべての呼び出しでOpenAlexの日次予算のコストと残高が報告されます

---

openalex_analyze_trends _ツール

• トレンド、分布、比較分析のために、サポートされている任意のフィールドでグループ化できます。集計前に対象集団を絞り込むには、filters と組み合わせます
• 1 ページあたり最大 200 グループ（デフォルト）です。カーソルがない場合、order: "count"（デフォルト）は件数順の上位 N 件を返し、それ以降のページはありません。order: "key" は、カーソルページネーションを使ってキーの昇順で個別の値を列挙します。ブール型フィールドは "key" を指定しても件数順を維持し、カーソルページネーションはサポートされません。cursor を指定すると、order が省略されている場合や "count" の場合でも、キー順が選択されます。OpenAlex ではキー順の走査中に、より前のグループへ折り返すことがあります。ページの先頭キーが以前のキーと重複した場合、または next_cursor がまだ存在していてもページの件数が少ないか空の場合は、走査を停止してください
• include_unknown（デフォルトは false）を指定すると、グループ化フィールドに値がないエンティティのグループが追加されます。このグループには is_unknown: true のフラグが付き、テキスト出力では不明としてラベル付けされます。group_by にネイティブの :include_unknown サフィックスを付けても、明示的に false が指定されている場合を含め、この機能が有効になります。両方を指定した場合、サフィックスは 1 回だけ追加されます。OpenAlex では、キーとして -111／-111.0（数値フィールド）、unknown（テキストフィールドおよび order: "key"）、または /unknown で終わる ID が使われます。このキーはセンチネルであり、フィルター値ではありません。ブール型フィールドにはこのようなグループはなく、値がない場合は false としてカウントされます
• key_display_name は常に含まれますが、OpenAlex からラベルが提供されない場合は null になります。その場合、テキスト出力では不明のグループを含め、グループキーが表示されます
• すべてのフィールドをグループ化できるわけではありません。生の日付フィールド、.search 演算子、from_*／to_* 範囲修飾子、fwci などの小数スコア、display_name、doi などの外部 ID フィールド、primary_location.source.country_code など関連エンティティから OpenAlex が参照するフィールドは拒否されます。openalex_describe_fields(entity_type, "group_by") で、グループ化できるフィールドを確認できます
• authorships.countries による works の group_by では、このフィールドについて OpenAlex が各 work の先頭 100 件の authorships のみをカウントすることが通知されます。すべての authorships をカウントするフィールドとして、authorships.institutions.country_code が示されます
• OpenAlex の 1 日あたりの予算コストと残高を報告します。集計の料金は、同じエンティティをページ分割して取得する場合より大幅に低く設定されています

---

openalex_resolve_name _tool

• 名前または部分的な名前を指定すると、オートコンプリート検索を実行します。最大10件の候補が、識別に役立つ情報（最後に所属した機関、ホスト組織、場所など）とともに返されます
• 識別子（OpenAlex ID、DOI、ORCID、ROR、PMID、ISSN、キーワード URL）は、単独で指定する場合も URL 形式で指定する場合も、その識別子が指すレコードに該当するエンティティタイプで直接解決されます。ROR は、組織の機関、助成機関、出版社の各レコードを同時に表すことがあります。entity_type が指定されていない場合（または別のタイプが指定されている場合）、3種類すべてを課金対象外の単一レコード取得として並行検索し、見つかったレコードをすべて機関、助成機関、出版社の順に返します。entity_type に institutions、funders、publishers のいずれかを指定すると、そのタイプだけに絞り込まれます。Crossref Funder Registry の DOI（10.13039/…）は、entity_type が works でない限り、助成機関として解決されます。PMCID は認識されますが、OpenAlex には登録されていないため何も解決されません
• 短い名前は OpenAlex ID と同じ形式を取ることがあります（キーワード p53 は出版社 P53 として読み取られます）。そのため、単独で指定した OpenAlex ID が解決されなかった場合は、次に名前として検索されます。entity_type が指定されていれば、そのタイプの範囲で検索され、通知には両方の検索結果が記載されます。実在する ID は、1回のリクエストで引き続き解決されます。entity_type: "keywords" の場合、この形式の値は最初からキーワード名として検索されます
• filters はオートコンプリート検索のみを絞り込み、entity_type の指定が必要です。entity_type を指定せずに filters を渡す名前クエリは、リクエスト前に拒否されます（filters_without_entity_type）。識別子の検索では無視され、その旨が通知されます。filters を使った名前検索で一致するものがない場合は、指定されたフィルターが通知に含まれ、まずフィルターを緩めるよう提案されます
• entity_type を指定した場合、OpenAlex のオートコンプリートは1,000文字を超える名前で失敗します。この失敗は query_too_long として1回だけ報告され、サービス停止として再試行されず、名前を短くするよう案内されます
• OpenAlex の日次予算の使用量と残高を報告します

---

openalex_get_citation_graph _tool

• direction はエッジを設定します。cites（シードを引用する論文）、cited_by（シード自身の参考文献リスト）、related_to（OpenAlex のアルゴリズムによる関連論文。通常は約8～30件ですが、空の場合もあります）
• seed_id には OpenAlex の論文 ID（単独で指定するか、OpenAlex のレコードページまたは API の URL を指定）、DOI、PMID を指定できます（PMCID は認識されますが、何も解決されません）。最初に実際の検索で検証されるため、存在しないシードは空のグラフではなく NotFound として失敗し、別のエンティティタイプの ID は上流への呼び出し前に id_type_mismatch として失敗します
• filters／sort／select（author_list を含む）と組み合わせて、グラフを絞り込めます。filters では cites／cited_by／related_to を設定できません。また、cited_works のようにこれらのエイリアスを設定することもできません。これらのキーは direction 用に予約されています
• カーソルページネーションに対応し、1ページあたり最大100件（デフォルトは25件）を返します
• openalex_search_entities と同じ64,000バイトのレスポンス上限と、著者情報の上限100件に関する説明が適用されます。ページから除外された論文は omitted に記載され、それらを返す openalex_search_entities 呼び出しとともに、OpenAlex の順序で表示されます
• シードの検証検索とグラフページの両方を対象とする OpenAlex の日次予算の使用量と、残高を報告します

openalex_describe_fields _ツール

• エンティティタイプとコンテキスト（filter、group_by、select）ごとに、有効なフィールド名をすべて列挙します。完全な一覧であり、省略されません
• group_by は、OpenAlex が集計キーとして受け付けないものをフィルターセットから除いたものです。対象は、日付の生フィールド、.search／.search.exact 演算子、from_*／to_* の範囲修飾子、およびライブ API で列挙されたすべてのフィールドをグループ化して見つかった、エンティティタイプごとのフィールドセットです。これには、fwci などの小数スコア、複数のソース年フィールド、display_name、外部 ID フィールドが含まれます
• created_date、updated_date と、それらの from_／to_ 形式は、フィルターとして一覧に含まれていますが、OpenAlex では有料プランでのみ利用できます。有料プランがない場合、これらを使ったフィルターは最初のリクエストで upstream_plan_required エラーとなり、再試行されません
• 任意の query を指定すると、フィールドを除外せずに名前の類似度順で結果を並べ替えます。ネストされた値の親オブジェクトも、リストの下のほうで引き続き見つけられます
• 生成されたフィールドカタログに基づいており、ライブ API の呼び出しはありません

---

openalex_literature_review _{プロンプト}

• 引数：topic は必須です。scope（narrow／broad）は任意で、デフォルトは narrow です
• エンティティの解決、文献の検索、主要な論文の特定、引用の追跡、研究状況の分析、調査結果の統合という6段階のワークフローを案内するユーザーメッセージを1つ返します
• scope によって検索ステップが変わります。narrow は、トピックを絞り込むフィルターを使った厳密な検索を優先します。broad は、関連する複数のトピック ID を横断するセマンティック検索を追加します

---

openalex_research_landscape _{プロンプト}

• 引数：topic は必須です
• トピック ID の解決、件数の推移、主な貢献者（機関／国／ジャーナル）、オープンアクセス率、資金源、最も引用された著作、成長中の研究フロントという7段階の定量的なワークフローを案内するユーザーメッセージを1つ返します
• 資金調達のステップでは funders.id でグループ化します。資金提供者を記載しているすべての著作をカウントし、各グループには資金提供者の名前を付けます。助成番号など、助成金レベルの質問には awards.* フィールドを引き続き使用します

機能

@cyanheads/mcp-ts-core を基盤としており、stdio および Streamable HTTP トランスポート、プラグイン可能な認証（none／jwt／oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレース機能を備えた構造化ログに対応しています。

OpenAlex 固有の機能：

• 型付けされた API クライアントによる ID の自動正規化（DOI、ORCID、ROR、PMID、PMCID、ISSN、http、https、またはスキームなしの OpenAlex レコードページおよび API の URL、PubMed／PubMed Central の URL）。PMCID は正規化されますが、OpenAlex ではインデックスされていないため、解決先はありません
• デフォルトでは API キー不要です。オプションの API キーを指定すると、レート制限と日次予算の上限が引き上げられます。また、オプションの mailto を指定すると、OpenAlex の polite pool に呼び出し元が登録されます
• HTTP ステータスコードを特定の MCP エラークラスに対応付けます（400 → InvalidParams。ただし、セマンティック検索でクエリ埋め込みに上流エラーが発生した場合は ServiceUnavailable。422 → ValidationError。429 → RateLimited。ただし、有料プラン限定のフィルターを拒否する 429 の場合は Forbidden）。上流のエラーメッセージも表示されます
• タイムアウトを考慮したリクエストの再試行と、AbortSignal によるキャンセルに対応しています

エージェントが扱いやすい出力：

• 出典情報 — API を呼び出すすべてのツールが、OpenAlex の日次予算の使用額、残高、リセットまでの時間（budget.costUsd、remainingUsd、resetsInSeconds）を報告します
• 実際に適用されたクエリの表示 — 検索、トレンド、引用グラフのレスポンスには、実際に実行された条件が含まれるため、リクエストを見直さなくても結果が空だった原因を特定できます
• 判別可能な出力コントラクト — 型付けされたエラー理由（entity_not_found、upstream_budget_exhausted、semantic_per_page_cap、reserved_filter_key など）には、それぞれ明示的な復旧のヒントが含まれます
• レスポンスの整形 — アブストラクトは OpenAlex の転置インデックス形式からプレーンテキストに再構成されます。また、タイトルのないレコードやパラテキストのレコードでは、display_name は補完されず null のままになります
• プロバイダーのテキストをそのまま保持 — OpenAlex から渡されるタイトル、アブストラクト、名前はサニタイズされません。HTML エンティティは WHATWG の全テーブルに基づいてデコードされ、コメントと HTML／JATS／MathML の書式タグは削除されます。CDATA のラッパーと IOP の <?CDATA …?> 数式マーカーは、TeX を保持したままラッパーを解除します。MathType の数式データ（% MathType!MTEF!…!44A1!）は削除されますが、それを表す TeX は残ります。また、二重にエスケープされた改行（リテラルの \n）はスペースになります。A < B、95% CI などのリテラルテキストや、\nu などの TeX は保持されます。識別子と URL のフィールド（id、doi、ids、orcid、ror、issn、*_url、lineages）は OpenAlex に保存されたとおりに返されるため、再度渡すとそれぞれ解決されます。テキスト出力では、そのテキストを Markdown 用にエスケープするため、*、<tag>、[x](y) などがそのまま表示されます。ID と、リンクとして表示される URL はバイト単位で同一のままです

はじめに

インストールせずに、ホストされているインスタンスに接続します：

claude mcp add --transport http openalex-mcp-server https://openalex.caseyjhand.com/mcp

または、ローカルで実行します：

claude mcp add openalex-mcp-server -- npx -y @cyanheads/openalex-mcp-server

その他のクライアントの場合は、MCP 設定ファイルに以下を追加します：

{
  "mcpServers": {
    "openalex-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/openalex-mcp-server"]
    }
  }
}

オプションの OPENALEX_API_KEY（無料の OpenAlex アカウントキー）を指定すると、匿名アクセスよりもレート制限と日次予算の上限が引き上げられます。OPENALEX_MAILTO を指定すると、OpenAlex の polite pool に登録されます。Docker またはソースからのビルドについては、サーバーの実行を参照してください。

設定

変数	説明	デフォルト
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_SESSION_MODE	HTTP セッションモード：stateless、stateful、または auto（stateful に解決されます）。サーバーはコード内で stateless を宣言しており、明示的に指定した値が優先されます。	stateless
MCP_AUTH_MODE	認証モード：none、jwt、または oauth。	none
MCP_ALLOWED_ORIGINS	HTTP トランスポートで許可するブラウザーの Origin ヘッダーをカンマ区切りで指定します。未設定の場合はループバックのみです。* を設定すると無効になります。	ループバックのみ
MCP_LOG_LEVEL	ログレベル（RFC 5424）。	debug
LOGS_DIR	ログファイルのディレクトリ（Node.js のみ）。	<project-root>/logs
STORAGE_PROVIDER_TYPE	ストレージバックエンド。	in-memory
OPENALEX_API_KEY	OpenAlex アカウントの API キー。上流に api_key= として送信されます（openalex.org/settings/api で無料取得できます）。指定しない場合は、匿名利用のレート制限が適用されます。	—
OPENALEX_MAILTO	OpenAlex に自分を識別してもらうため、上流に mailto= として送信するメールアドレス（「polite pool」用）。API キーとは別の、任意の識別情報です。	—
OPENALEX_BASE_URL	OpenAlex API のベース URL。	https://api.openalex.org
OPENALEX_FILTER_STRING_INPUT	openalex_search_entities で、曖昧さのないネイティブのフィルター文字列を受け付けます。false に設定すると、レコードオブジェクトが必須になります。無効なブール値を指定すると、起動に失敗します。	true
OPENALEX_CLAMP_PER_PAGE	上限を超える正の整数の per_page を、要求値と適用値を通知したうえで上限値に調整します（検索／引用分析では 100、分析では 200）。false に設定すると、告知済みの上限を超える値を再び拒否します。無効なブール値を指定すると、起動に失敗します。セマンティック検索とサンプルの上限は引き続き拒否されます。	true
OTEL_ENABLED	OpenTelemetry の計装（スパン、メトリクス、完了ログ）を有効にします。	false

オプションで上書きできる設定の全一覧は .env.example を参照してください。

サーバーの実行

ローカル開発

Bun v1.4.0 以上（または Node.js v24 以上）が必要です。

• クローンしてインストールする：

  git clone https://github.com/cyanheads/openalex-mcp-server.git
  cd openalex-mcp-server && bun install
  cp .env.example .env   # optionally set OPENALEX_API_KEY
  

• ビルドして実行する：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• チェックとテストを実行する：

  bun run devcheck   # Lints, formats, type-checks
  bun run test       # Runs the test suite
  

Docker

docker run --rm -e OPENALEX_API_KEY=your-key -p 3010:3010 ghcr.io/cyanheads/openalex-mcp-server:latest

イメージのデフォルトは HTTP トランスポート、ステートレスセッションモードで、ログは /var/log/openalex-mcp-server に出力されます。MCP クライアントから stdio 経由で実行するには、"command": "docker" と "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/openalex-mcp-server:latest"] を使用します。ローカルでビルドするには docker build -t openalex-mcp-server . を実行します。OpenTelemetry のピア依存関係はデフォルトでインストールされます。省略するには、--build-arg OTEL_ENABLED=false を指定してビルドします。

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリーポイントです。ツールとプロンプトを登録します。
src/config/	サーバー固有の環境変数の解析と、Zod による検証を行います。
src/mcp-server/tools/definitions/	ツール定義（*.tool.ts）。
src/mcp-server/prompts/definitions/	プロンプト定義（*.prompt.ts）。
src/services/openalex/	OpenAlex API クライアント、フィールドカタログ、ドメイン型。
tests/	src/ の構成を反映したユニットテストと統合テスト。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックでは try/catch を使用しません
• ログには ctx.log を、ストレージには ctx.state を使用します
• OpenAlex のレスポンスは、未加工のペイロードを検証し、ドメイン型に正規化してから、出力スキーマを返すようにラップします。不足しているフィールドを決して捏造しないでください
• エンティティで絞り込む前に、必ず openalex_resolve_name を使用して名前を ID に解決してください

貢献

問題の報告を歓迎します。提出前にチェックを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。