genius-mcp-server

genius-mcp-server

一个用于与 Genius API 交互的 Model Context Protocol (MCP) 服务。它允许 MCP 客户端应用（例如 Claude for Desktop 或 VS Code GitHub Copilot）搜索歌词、艺术家，并从 Genius.com 获取歌曲和艺术家的详细信息。

功能

此 MCP 服务提供了 Genius API 的以下功能：

• 工具（Tools）： 允许大模型执行操作或搜索信息。
  • genius-search：根据给定的词语搜索歌曲、艺术家或网页。
  • genius-list-artist-songs：根据艺术家的 ID 列出该艺术家的歌曲。
• 资源（Resources）： 允许客户端或大模型访问特定数据。
  • 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 Key（Client Access Token）。

获取 Genius API Key

1. 访问 Genius API Client management 页面。
2. 如果还没有 API 客户端，请创建一个。
3. 点击“Generate Access Token”以获取 Client Access Token。此令牌仅允许读取公共端点，足以用于此基础服务中实现的工具和资源。
4. 请妥善保管此令牌。 不要公开分享。

使用 npx 安装和运行

运行此服务最简单的方法是使用 npx。npx 会直接从 npm 下载并运行服务，无需全局安装。

1. 打开终端或命令行。

2. 将 Genius API Key 设置为环境变量。将 TU_CLIENT_ACCESS_TOKEN_AQUI 替换为你的实际密钥。

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

3. 使用 npx 和你的包名运行服务（发布时请确保包名与 package.json 中使用的名称一致）：

   npx -y genius-mcp-server # 以包名 'genius-mcp-server' 为例
   

   服务将启动并等待 MCP 客户端通过 stdio 建立连接。你将在终端中看到初始化消息（输出到 stderr）。

   按 Ctrl+C 停止服务。

使用 MCP 客户端进行配置

要将此服务与 Claude for Desktop 等 MCP 客户端应用配合使用，你需要配置客户端，使其通过 npx 启动你的服务，并将 Genius API Key 作为环境变量传入。

以下是 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”服务应该会显示出来，并列出可用的工具和资源。提示词可能会显示为斜杠命令（/）。

如何将此服务与大模型配合使用（以 Claude 为例）

服务连接到 MCP 客户端（例如 Claude）后，大模型便可使用工具并访问资源。

• 搜索： 可以向 Claude 提出如下问题：
  • “Find songs by Taylor Swift on Genius.”
  • “Search Genius for the song 'Lose Yourself'.”
  • “Look up the artist Kendrick Lamar on Genius.” Claude 应该能够识别搜索意图，并请求你批准使用 genius-search 工具。
• 获取歌曲/艺术家详情： 要使用 genius-song 或 genius-artist 资源，大模型或客户端需要知道数字 ID（例如，可通过之前的搜索获取）。大模型请求读取资源的方式取决于客户端的实现。你可能需要一个额外的工具，用于接收 ID 并生成包含资源内容的大模型提示词，也可能需要一个带有资源浏览界面的客户端。
• 使用搜索提示词： 如果你的客户端支持将提示词用作斜杠命令，可以尝试输入 /genius-search-prompt 来生成预定义的提示词。

本地开发

如果你想修改或为此服务做贡献：

1. 克隆仓库。
2. 安装依赖项：npm install
3. 在根目录下创建 .env 文件，并填入你的 Client Access Token：GENIUS_ACCESS_TOKEN=TU_CLAVE。
4. 编译 TypeScript 代码：npm run build
5. 在本地运行（在终端中配置好环境变量）：npm start 或 npm run dev（用于编译并运行）。

贡献

欢迎贡献！欢迎在仓库中提交 issues 或 pull requests，以改进此服务（添加更多 endpoints、支持 User Access Tokens/OAuth 等）。

许可证

本项目采用 ISC 许可证。