genius-mcp-server

genius-mcp-server

Genius APIと連携するためのModel Context Protocol（MCP）サーバーです。Claude for DesktopやVS Code GitHub CopilotなどのMCPクライアントアプリケーションから、Genius.comの歌詞やアーティストを検索したり、楽曲やアーティストの詳細を取得したりできます。

特徴

このMCPサーバーは、Genius APIの以下の機能を公開します。

• ツール（Tools）： LLMがアクションを実行したり、情報を検索したりできます。
  • genius-search：指定した語句で楽曲、アーティスト、ウェブページを検索します。
  • genius-list-artist-songs：IDを指定して、特定のアーティストの楽曲一覧を取得します。
• リソース（Resources）： クライアントやLLMが特定のデータにアクセスできます。
  • genius-song：IDを指定して楽曲の詳細を取得します（URI テンプレート genius://songs/{id}）。
  • genius-artist：IDを指定してアーティストの詳細を取得します（URI テンプレート genius://artists/{id}）。
• プロンプト（Prompts）： 一般的なやり取りを始めるための再利用可能なテンプレートです。
  • genius-search-prompt：Geniusで検索を始めるための基本的なプロンプトです。

要件

• Node.js（バージョン16以上）がインストールされていること。
• npm（Node.jsに付属）または uv がインストールされていること。
• APIにアクセスするための Genius APIキー（Client Access Token）。

Genius APIキーの取得

1. Genius APIクライアント管理ページにアクセスします。
2. APIクライアントをまだ作成していない場合は、新しく作成します。
3. 「Generate Access Token」をクリックして、Client Access Tokenを取得します。このトークンでアクセスできるのは公開エンドポイントの読み取りのみです。この基本的なサーバーに実装されているツールとリソースには、それで十分です。
4. このトークンは安全に保管してください。 公開しないでください。

npxを使ったインストールと実行

このサーバーを実行する最も簡単な方法は、npxを使うことです。npxはグローバルにインストールしなくても、npmからサーバーを直接ダウンロードして実行します。

1. ターミナルまたはコマンドラインを開きます。

2. Genius APIキーを環境変数として設定します。TU_CLIENT_ACCESS_TOKEN_AQUIを実際のキーに置き換えてください。

   # MacOS / Linux (bash, zsh, etc.)
   export GENIUS_CLIENT_ACCESS_TOKEN=TU_CLIENT_ACCESS_TOKEN_AQUI
   
   # En Windows (Command Prompt)
   set GENIUS_CLIENT_ACCESS_TOKEN=TU_CLIENT_ACCESS_TOKEN_AQUI
   
   # En Windows (PowerShell)
   $env:GENIUS_CLIENT_ACCESS_TOKEN="TU_CLIENT_ACCESS_TOKEN_AQUI"
   

3. npxとパッケージ名を使ってサーバーを実行します（公開時にpackage.jsonで使用した正しい名前であることを確認してください）。

   npx -y genius-mcp-server # Usando el nombre de paquete 'genius-mcp-server' como ejemplo
   

   サーバーが起動し、stdio経由でMCPクライアントからの接続を待ち受けます。ターミナルに初期化メッセージが表示されます（stderr）。

   サーバーを停止するには、Ctrl+Cを押します。

MCP クライアントでの設定

Claude for Desktop などの MCP クライアントアプリケーションでこのサーバーを使用するには、npx を使ってサーバーを起動し、Genius の API キーを環境変数として渡すようクライアントを設定する必要があります。

Claude for Desktop の設定例を以下に示します。

1. Claude Desktop の設定ファイルを開きます。

   • macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json ファイルが存在しない場合は、作成してください。

2. mcpServers セクションにサーバーのエントリを追加します。TU_CLIENT_ACCESS_TOKEN_AQUI を実際のキーに置き換えてください！

   {
     "mcpServers": {
       "genius-api": {
         // Claude のインターフェースに表示される名前
         "command": "npx",
         "args": [
           "-y",
           "genius-mcp-server" // <-- npm で公開したパッケージ名
         ],
         "env": {
           "GENIUS_ACCESS_TOKEN": "TU_CLIENT_ACCESS_TOKEN_AQUI" // キーを環境変数として渡します
         }
       }
     }
   }
   

   セキュリティに関する注意： 設定ファイル内の環境変数としてシークレットを渡す方法は、他のアプリケーションがそのファイルやプロセスにアクセスできる場合、最も安全な選択肢とは限りません。一部の MCP クライアント（VS Code Copilot など）では、より安全なシークレット管理機能が提供されている場合があります。claude_desktop_config.json を使用する Claude Desktop では、これが一般的な方法です。

3. claude_desktop_config.json ファイルを保存し、Claude for Desktop を完全に再起動します。

4. 再起動後、Claude のインターフェースで MCP アイコンを探します。「Genius API」サーバーが表示され、利用可能なツールとリソースが一覧表示されるはずです。プロンプトはスラッシュコマンド（/）として表示される場合があります。

LLM でサーバーを使用する方法（Claude の例）

サーバーを MCP クライアント（例：Claude）に接続すると、LLM はツールを使用し、リソースにアクセスできるようになります。

• 検索： Claude に次のように尋ねます。
  • 「Genius で Taylor Swift の曲を探してください。」
  • 「Genius で曲『Lose Yourself』を検索してください。」
  • 「Genius でアーティストの Kendrick Lamar を調べてください。」 Claude は検索の意図を認識し、genius-search ツールの使用許可を求めるはずです。
• 曲／アーティストの詳細を取得： genius-song または genius-artist リソースを使用するには、LLM またはクライアントが数値 ID を把握している必要があります（たとえば、事前に検索して取得します）。LLM がリソースの読み取りを要求する方法は、クライアントの実装によって異なります。ID を受け取り、リソースの内容を含むプロンプトを LLM 向けに生成する追加のツールや、リソースを参照する UI を備えたクライアントが必要になる場合があります。
• 検索プロンプトを使用： クライアントがスラッシュコマンド形式のプロンプトに対応している場合は、/genius-search-prompt と入力して、定義済みのプロンプトを生成できます。

ローカルでの開発

サーバーを変更または改善に貢献する場合は、次の手順に従ってください。

1. リポジトリをクローンします。
2. 依存関係をインストールします：npm install
3. ルートに Client Access Token を含む .env ファイルを作成します：GENIUS_ACCESS_TOKEN=TU_CLAVE。
4. TypeScript コードをビルドします：npm run build
5. ローカルで実行します（ターミナルで環境変数を設定した状態で）：npm start または npm run dev（ビルドして実行します）。

貢献

貢献を歓迎します！このサーバーを改善するため、リポジトリで issue や pull request を自由に作成してください（エンドポイントの追加、User Access Token/OAuth の処理など）。

ライセンス

このプロジェクトは ISC ライセンスの下でライセンスされています。