Genius MCP Server

---

目录

• 功能简介
• 工具
• 提示词
• 开始使用
  • 1. 获取 Genius API 令牌
  • 2. 配置环境变量
  • 3. 使用 Python 运行
  • 4. 使用 Docker 运行
• 传输模式
• 连接到 MCP 客户端
• 注释可信度等级
• 项目结构
• 许可证

---

功能简介

Genius MCP 服务将 Genius.com 知识库开放给任何兼容 MCP 的 AI 客户端（Claude Desktop、Claude Code、Cursor 等）。它可以让 AI：

• 按名称搜索歌曲和艺人
• 获取完整的歌曲元数据——标题、专辑、发行日期、歌词状态和 Genius 编辑描述
• 获取艺人简介——个人简介、粉丝数、认证状态
• 浏览艺人的音乐作品目录——按人气或发行日期排序，也可以查看包含曲目列表的完整专辑列表
• 阅读注释——针对特定歌词片段的社群和艺人认证解释，每条注释都带有可信度等级，让 AI 知道应给予多大权重
• 阅读专辑封面注释——直接标注在专辑封面图片上的社群解释，介绍视觉元素、象征意义和艺术构思
• 探索歌曲关联——了解一首歌采样、插值、翻唱或混音了哪些作品，以及之后有哪些歌曲采样了它
• 查询歌曲署名信息——词曲作者、制作人、参与艺人和自定义演出角色（混音工程师、录音室、唱片公司）
• 运行预置分析提示词，一次性收集所有相关数据，并要求 AI 深入分析歌曲或艺人

---

工具

一些工具会使用你的访问令牌调用 Genius 官方 API（api.genius.com）。其他工具使用 lyricsgenius Python 库，该库会访问 Genius 未公开文档的公共 API——这些端点不属于官方 API 契约，可能随时变更，恕不另行通知。

工具	描述	后端
search_song	在 Genius 中搜索与查询匹配的歌曲。返回歌曲 ID、标题、艺人和注释数量。	官方 API
get_song_details	根据歌曲的 Genius ID 获取完整元数据和编辑撰写的简介。	官方 API
get_song_annotations	获取歌曲的所有注释，可按可信度级别（artist_verified、accepted、unreviewed）筛选。	官方 API
get_annotation_detail	根据注释 ID 获取单条注释的全文和元数据。	官方 API
get_song_questions_and_answers	分页获取用户提交的歌曲问题和答案。仅返回已有获采纳答案的问题。	lyricsgenius（未公开文档的公共 API）
get_song_relationships	获取歌曲的音乐关联信息——采样、插值、翻唱、混音或翻译了哪些作品，以及哪些后续歌曲采样或翻唱了它。仅返回至少关联一首歌曲的关系类型。	官方 API
get_song_credits	获取歌曲的创作和制作署名：词曲作者、制作人、客串艺人和自定义演出角色（例如混音工程师、录音室、唱片公司）。	官方 API
search_artist	按名称在 Genius 中搜索艺人。返回艺人 ID 和基本个人资料信息。	官方 API
get_artist_details	根据艺人的 Genius ID 获取完整个人资料和编辑撰写的简介。	官方 API
get_artist_songs	列出艺人的歌曲，可按 popularity 或 release_date 排序，并支持分页。	官方 API
get_artist_albums	以分页专辑列表的形式获取艺人的完整唱片目录，其中包含专辑 ID。	lyricsgenius（未公开文档的公共 API）
search_album	在 Genius 中搜索与查询匹配的专辑。返回专辑 ID、名称、艺人名称和发行日期。	lyricsgenius（未公开文档的公共 API）
get_album_details	根据 Genius 专辑 ID 获取专辑的元数据、完整排序曲目列表和封面图列表。每首曲目都包含歌曲 ID，可用于串联其他工具。第一张封面图始终是专辑主封面；带注释的图片包含 annotation_id。	官方 API + lyricsgenius
get_cover_art_annotations	获取特定专辑封面图片上的完整注释——正文、可信度级别、作者和投票数。需要 cover_art_id 和 album_id（均可从 get_album_details 获取）。仅对带有 annotation_id 的封面图片调用。	lyricsgenius（未公开文档的公共 API）

---

提示词

提示词是预先构建的多步骤工作流，用于从 Genius 收集数据，并以结构化上下文提供给 AI。

analyze-song

参数： song_title（必填），artist_name（可选）

搜索歌曲，获取其完整元数据和编辑撰写的简介，检索所有注释（按可信度级别排序），并让 AI 深入分析歌曲的含义、主题和文化背景。

artist-deep-dive

参数： artist_name（必填）

获取艺人的完整简介、其最受欢迎的前 3 首歌曲的元数据和艺人认证注释（如有），并让 AI 概述该艺人的主题、风格和影响。

---

开始使用

1. 获取 Genius API 令牌

1. 前往 https://genius.com/api-clients 并登录。
2. 创建新的 API 客户端。
3. 复制 Client Access Token——这是你要用于 GENIUS_ACCESS_TOKEN 的值。

2. 配置环境变量

复制示例环境文件并填入你的令牌：

cp .env.example .env

编辑 .env：

# Required — your Genius API access token
GENIUS_ACCESS_TOKEN=your_token_here

# Transport mode:
# true  → run as a Streamable HTTP server on port 8080
# false → run in stdio mode (for Claude Desktop)
STREAMABLE_HTTP=true

3. 使用 Python 运行

要求： Python 3.11+

安装依赖：

pip install -r requirements.txt

运行服务：

python main.py

服务将以 http://127.0.0.1:8080 启动（Streamable HTTP 模式），或根据 STREAMABLE_HTTP 设置以 stdio 模式启动。

4. 使用 Docker 运行

Streamable HTTP 模式（默认）：

docker compose up --build

服务将以 genius-mcp-server 的名称运行，端口为 8080。.env 文件会挂载到容器中——启动前请确保该文件存在且包含你的令牌。

stdio 模式（例如，通过 Docker 连接 Claude Desktop）：

在 .env 中设置 STREAMABLE_HTTP=false，然后运行：

docker run --rm -i --env-file .env $(docker build -q .)

---

传输模式

模式	STREAMABLE_HTTP	使用场景
Streamable HTTP	true（默认）	Claude Code、远程 MCP 客户端、基于 Web 的工具
stdio	false	Claude Desktop、本地 CLI 集成

---

连接到 MCP 客户端

Claude Code（Streamable HTTP）

claude mcp add genius --transport http http://127.0.0.1:8080/mcp

Claude Desktop（stdio）

在 .env 中设置 STREAMABLE_HTTP=false 后，将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "genius": {
      "command": "python",
      "args": ["/absolute/path/to/genius-mcp/main.py"],
      "env": {
        "GENIUS_ACCESS_TOKEN": "your_token_here",
        "STREAMABLE_HTTP": "false"
      }
    }
  }
}

---

注释信任级别

服务返回的每条注释都包含 trust_level 字段，便于 AI 判断来源的可靠性：

信任级别	含义
artist_verified	由艺人撰写或确认。应视为真实依据。
accepted	已由 Genius 编辑团队审核并批准。质量较高。
unreviewed	由社区用户提交，尚未审核。应视为一种解读。

get_song_annotations 工具接受 filter 参数，可仅获取特定信任级别的注释。

---

项目结构

genius-mcp/
├── main.py                    # Entry point — configures transport and starts the server
├── app.py                     # FastMCP app instance
├── mcp_components/
│   ├── genius_api.py          # Async HTTP client for the Genius API
│   ├── mcp_tools.py           # MCP tool definitions
│   └── mcp_prompts.py         # MCP prompt definitions
├── tests/
│   ├── test_mcp_server_initialization.py
│   └── test_mcp_server_tools.py
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
└── .env.example

---

许可证

MIT