Smithsonian MCP

🚀 史密森学会オープンアクセスMCPサーバー

このモデルコンテキストプロトコル (MCP) サーバーは、AIアシスタントが史密森学会のオープンアクセスコレクションにアクセスできるようにします。このサーバーを使用すると、Claude DesktopなどのAIツールが、アメリカの国立博物館の300万点以上のコレクションオブジェクトを検索、探索、分析できます。

🚀 クイックスタート

オプション1: npm/npxによるインストール (最も簡単)

npmパッケージには自動的なPython依存関係管理が含まれており、すべてのプラットフォームで動作します。

# グローバルにインストール
npm install -g @molanojustin/smithsonian-mcp

# またはnpxで直接実行 (インストール不要)
npx -y @molanojustin/smithsonian-mcp

# APIキーを設定
export SMITHSONIAN_API_KEY=your_key_here

# サーバーを起動
smithsonian-mcp

オプション2: 自動セットアップ (Pythonユーザーにおすすめ)

拡張されたセットアップスクリプトには以下が含まれています。

• ✅ APIキー検証 - 保存する前にキーをテストします
• ✅ サービスインストール - システムサービスとして自動インストールします
• ✅ Claude Desktop設定 - 自動設定します
• ✅ ヘルスチェック - すべてが正常に動作することを確認します

macOS/Linux:

chmod +x setup.sh
./setup.sh

Windows:

.\setup.ps1

オプション3: 手動セットアップ

1. APIキーを取得: api.data.gov/signup (無料)
2. インストール: pip install -r requirements.txt
3. 設定: .env.exampleを.envにコピーし、APIキーを設定します
4. テスト: python examples/test-api-connection.py

セットアップの検証

インストールを確認するために検証スクリプトを実行します。

python scripts/verify-setup.py

✨ 主な機能

コア機能

• コレクション検索: 19の史密森学会の博物館にまたがる300万点以上のオブジェクトを検索できます
• オブジェクト詳細: 完全なメタデータ、説明、出所情報を取得できます
• 展示中ステータス: ⭐ 新機能 - 現在実際に展示されているオブジェクトを見つけることができます
• 画像アクセス: 高解像度の画像 (利用可能な場合はCC0ライセンス) を取得できます
• 3Dモデル: 利用可能な場合はインタラクティブな3Dコンテンツを取得できます
• 博物館情報: すべての史密森学会の施設を閲覧できます

AI統合

• 12のMCPツール: コレクションデータの検索、フィルタリング、取得、展示ステータスの確認、コンテキストの取得ができます
• スマートコンテキスト: AIアシスタント用のコンテキストデータソースを提供します
• 豊富なメタデータ: 完全なオブジェクト情報と展示詳細を提供します
• 展示計画: ⭐ 新機能 - 現在展示されているオブジェクトを見つけて探索するためのツールを提供します

📚 ドキュメント

Claude Desktop

オプション1: npm/npxを使用する (おすすめ)

1. 設定 (claude_desktop_config.json):

{
  "mcpServers": {
    "smithsonian_open_access": {
      "command": "npx",
      "args": ["-y", "@molanojustin/smithsonian-mcp"],
      "env": {
        "SMITHSONIAN_API_KEY": "your_key_here"
      }
    }
  }
}

オプション2: Pythonインストールを使用する

1. 設定 (claude_desktop_config.json):

{
  "mcpServers": {
    "smithsonian_open_access": {
      "command": "python",
      "args": ["-m", "smithsonian_mcp.server"],
      "env": {
        "SMITHSONIAN_API_KEY": "your_key_here"
      }
    }
  }
}

または、提供されているclaude-desktop-config.jsonをコピーし、APIキーを更新してください

2. テスト: Claudeに「What Smithsonian museums are available?」と尋ねます。

mcpo統合 (MCP Orchestrator)

mcpoは、複数のMCPサーバーをOpenAPI/HTTPエンドポイントに変換するMCPオーケストレーターです。複数のサービスを単一のsystemdサービスに統合するのに最適です。

インストール

# mcpoをインストール
pip install mcpo

# またはuvxを使用
uvx mcpo --help

設定

mcpo-config.jsonファイルを作成します。

{
  "mcpServers": {
    "smithsonian_open_access": {
      "command": "python",
      "args": ["-m", "smithsonian_mcp.server"],
      "env": {
        "SMITHSONIAN_API_KEY": "your_api_key_here"
      }
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "time": {
      "command": "uvx",
      "args": ["mcp-server-time", "--local-timezone=America/New_York"]
    }
  }
}

mcpoで実行

# ホットリロードでmcpoを起動
mcpo --config mcpo-config.json --port 8000 --hot-reload

# APIキー認証を使用する場合
mcpo --config mcpo-config.json --port 8000 --api-key "your_secret_key"

# エンドポイントにアクセス:
# - 史密森学会: http://localhost:8000/smithsonian_open_access
# - メモリ: http://localhost:8000/memory
# - 時間: http://localhost:8000/time
# - APIドキュメント: http://localhost:8000/docs

systemdサービス

/etc/systemd/system/mcpo.serviceを作成します。

[Unit]
Description=MCP Orchestrator Service
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/your/config
Environment=PATH=/path/to/venv/bin
ExecStart=/path/to/venv/bin/mcpo --config mcpo-config.json --port 8000
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

# サービスを有効化して起動
sudo systemctl enable mcpo
sudo systemctl start mcpo
sudo systemctl status mcpo

mcpoのトラブルシューティング

"ModuleNotFoundError: No module named 'smithsonian_mcp'"

これは、mcpoがSmithsonian MCPモジュールを見つけられない場合に発生します。以下の方法で修正します。

1. mcpo設定で絶対Pythonパスを使用する

{
  "command": "/full/path/to/your/project/.venv/bin/python",
  "env": {
    "PYTHONPATH": "/full/path/to/your/project"
  }
}

2. パスを確認する

# Python実行ファイルが存在することを確認
ls -la /path/to/your/project/.venv/bin/python

# モジュールのインポートをテスト
/path/to/your/project/.venv/bin/python -c "import smithsonian_mcp; print('OK')"

3. セットアップスクリプトで設定を再生成する

./setup.sh  # 正しいパスでmcpo-config.jsonを作成します

"Connection closed"エラー

• APIキーが有効で、環境に設定されていることを確認します
• 仮想環境にすべての依存関係がインストールされていることを確認します
• MCPサーバーが手動で起動できることを確認します: python -m smithsonian_mcp.server --test

"Port 8000 already in use"

# ポートを使用しているものを確認
lsof -i :8000
# または別のポートを使用
mcpo --config mcpo-config.json --port 8001

VS Code

1. ワークスペースを開く: code .vscode/smithsonian-mcp-workspace.code-workspace
2. タスクを実行する: MCPサーバーのデバッグ、テスト、開発を行います
3. Claudeコード: 史密森学会のデータを使用したAI支援開発を行います

利用可能なデータ

• 19の博物館: NMNH、NPG、SAAM、NASM、NMAHなど
• 300万点以上のオブジェクト: デジタル化されたコレクションアイテム
• CC0コンテンツ: 商用利用可能な公共ドメインの素材
• 豊富なメタデータ: 作成者、日付、素材、寸法など
• 高解像度画像: プロの写真撮影による画像
• 3Dモデル: インタラクティブなデジタルアセット

MCPツール

検索と発見

• search_collections - フィルターを使用した高度な検索 (現在はon_viewパラメーターを含みます)
• get_object_details - 詳細なオブジェクト情報を取得します
• search_by_unit - 博物館固有の検索を行います
• ⭐ get_objects_on_view - 新機能 - 現在実際に展示されているオブジェクトを見つけます
• ⭐ check_object_on_view - 新機能 - 特定のオブジェクトが展示中かどうかを確認します

情報とコンテキスト

• get_smithsonian_units - すべての博物館のリストを取得します
• get_collection_statistics - コレクションの統計情報を取得します
• get_search_context - 検索結果をコンテキストデータとして取得します
• get_object_context - 詳細なオブジェクト情報をコンテキストとして取得します
• get_units_context - 施設のリストをコンテキストデータとして取得します
• get_stats_context - コレクションの統計情報をコンテキストとして取得します
• ⭐ get_on_view_context - 新機能 - 現在展示されているオブジェクトをコンテキストとして取得します

新機能: 展示中機能 🎨

フェーズ1の新機能

MCPサーバーには、現在史密森学会の博物館で実際に展示されているオブジェクトを見つけるための包括的なサポートが追加されました。これは、史密森学会の公式APIドキュメントに沿った優先機能です。

主要機能

• 展示中オブジェクトの検索: 現在展示されているオブジェクトを検索できます
• 展示ステータスの確認: 特定のオブジェクトが展示中かどうかを確認できます
• 博物館でフィルタリング: 特定の史密森学会の施設で展示されているものを見つけることができます
• 展示詳細: 展示のタイトルと場所情報にアクセスできます
• 複合フィルター: 展示中ステータスと他の検索条件を組み合わせることができます

使用例

現在展示中のすべてのオブジェクトを見つける:

# Claudeに尋ねる:
"What objects are currently on physical exhibit at the Smithsonian?"

# またはフィルターを使用する:
"Show me paintings currently on display at the National Portrait Gallery"

特定のオブジェクトが展示中かどうかを確認する:

# Claudeに尋ねる:
"Is object edanmdm-nmah_1234567 currently on display?"

他のフィルターと組み合わせる:

# Claudeに尋ねる:
"Find CC0 licensed objects currently on view with high-resolution images"

ツール詳細

get_objects_on_view

現在実際に展示されているオブジェクトを見つけます。

パラメーター:

• unit_code (オプション): 史密森学会の施設でフィルタリングします (例: "NMNH", "NPG")
• limit: 最大結果数 (デフォルト: 20, 最大: 100)
• offset: ページネーションのオフセット

戻り値: 現在展示中のオブジェクトを含む検索結果

check_object_on_view

特定のオブジェクトが現在展示されているかどうかを確認します。

パラメーター:

• object_id: オブジェクトの一意の識別子

戻り値: 展示ステータスを含むオブジェクト詳細

search_collections (拡張版)

現在は、展示中ステータスでフィルタリングするためのon_viewパラメーターが含まれています。

新しいパラメーター:

• on_view (ブール値): 展示ステータスでオブジェクトをフィルタリングします
  • True: 現在展示中のオブジェクトのみ
  • False: 展示中ではないオブジェクトのみ
  • None: フィルタリングなし (デフォルト)

実装ノート

この機能は、オブジェクトが現在実際の展示で公開されているかどうかを示す史密森学会のonPhysicalExhibitメタデータフィールドに基づいています。実装には以下が含まれています。

• EDANメタデータモデルv1.09との完全なAPIアライメント
• onPhysicalExhibit:"Yes"クエリを使用したフィールド検索サポート
• 包括的なテストカバレッジ (15の単体テスト)
• 展示メタデータの抽出 (タイトル、場所)

ユースケース

研究と教育

• 学術研究: 多段階の学術調査
• レッスンプランニング: 教育コンテンツの作成
• オブジェクト分析: 文化オブジェクトの詳細な研究

キュレーションと展示

• 展示計画: テーマ別のオブジェクト選択と来場者計画
• 来場計画: ⭐ 新機能 - 来場前に現在展示されているものを見つける
• 展示研究: ⭐ 新機能 - 現在の展示トレンドと展示を研究する
• コレクション開発: ギャップ分析と収集
• デジタルヒューマニティーズ: 大規模な分析プロジェクト

開発

• 文化アプリ: 博物館データを使用したアプリケーション
• 教育ツール: インタラクティブな学習プラットフォーム
• API統合: プロの開発ワークフロー

必要条件

npm/npxインストールの場合:

• Node.js 16.0以上
• Python 3.10以上 (自動検出され、依存関係が管理されます)
• api.data.gov からのAPIキー (無料)
• APIアクセスのためのインターネット接続

Pythonインストールの場合:

• Python 3.10以上
• api.data.gov からのAPIキー (無料)
• APIアクセスのためのインターネット接続

テスト

npm/npxを使用する場合:

# API接続をテスト
smithsonian-mcp --test

# MCPサーバーを実行
smithsonian-mcp

# ヘルプを表示
smithsonian-mcp --help

Pythonを使用する場合:

# API接続をテスト
python examples/test-api-connection.py

# MCPサーバーを実行
python -m smithsonian_mcp.server

# テストスイートを実行
pytest tests/

# 展示中機能のテストを実行
pytest tests/test_on_view.py -v

# 基本テストを実行
pytest tests/test_basic.py -v

# 完全なセットアップを検証
python scripts/verify-setup.py

# VS Codeタスク (ワークスペースを使用する場合)
# - MCPサーバーをテスト
# - テストを実行
# - コードをフォーマット
# - コードをリント

サービス管理

Linux (systemd)

# サービスを起動
systemctl --user start smithsonian-mcp

# サービスを停止
systemctl --user stop smithsonian-mcp

# ステータスを確認
systemctl --user status smithsonian-mcp

# 起動時に有効化
systemctl --user enable smithsonian-mcp

macOS (launchd)

# サービスを読み込む
launchctl load ~/Library/LaunchAgents/com.smithsonian.mcp.plist

# サービスをアンロード
launchctl unload ~/Library/LaunchAgents/com.smithsonian.mcp.plist

# ステータスを確認
launchctl list | grep com.smithsonian.mcp

Windows

# サービスを起動
Start-Service SmithsonianMCP

# サービスを停止
Stop-Service SmithsonianMCP

# ステータスを確認
Get-Service SmithsonianMCP

トラブルシューティング

一般的な問題

"API key validation failed"

• api.data.gov/signup から無料のキーを取得します
• APIキーに余分なスペースがないことを確認します
• .envファイルにSMITHSONIAN_API_KEY=your_key_hereが含まれていることを確認します

"Service failed to start"

• python scripts/verify-setup.pyを実行して診断します
• ログを確認します: journalctl --user -u smithsonian-mcp (Linux) または ~/Library/Logs/com.smithsonian.mcp.log (macOS)
• 仮想環境がアクティブ化されていることを確認します

"Claude Desktop not connecting"

• 設定後にClaude Desktopを再起動します
• Claude Desktopの設定ファイルが存在し、正しいパスが含まれていることを確認します
• MCPサーバーが実行中であることを確認します: python -m smithsonian_mcp.server

"Module import errors"

• 仮想環境をアクティブ化します: source .venv/bin/activate (Linux/macOS) または .\venv\Scripts\Activate.ps1 (Windows)
• 依存関係を再インストールします: pip install -r requirements.txt

ヘルプを得る方法

1. 検証スクリプトを実行します: python scripts/verify-setup.py
2. 統合ガイド を確認します
3. GitHubの問題 を確認します

📚 ドキュメント

• 統合ガイド: Claude DesktopとVS Codeのセットアップ
• APIリファレンス: 完全なツールとリソースのドキュメント
• サンプル: 実際の使用シナリオ
• デプロイメントガイド: 本番環境でのデプロイオプション

コントリビュートする方法

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更を加えます
4. テストを実行します
5. プルリクエストを送信します

📄 ライセンス

MITライセンス - 詳細はLICENSEファイルを参照してください。

謝辞

• 史密森学会 のオープンアクセスコレクション
• api.data.gov のAPIインフラストラクチャ
• FastMCP チームのMCPフレームワーク
• モデルコンテキストプロトコル コミュニティ