Metadata-Version: 2.4
Name: bilibili-mcp-python
Version: 0.1.0
Summary: MCP server for Bilibili API
Author-email: Yungaoluo <1925001814@qq.com>
License: MIT
Keywords: api,bilibili,mcp,model-context-protocol,video
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.10
Requires-Dist: bilibili-api-python>=16.2.0
Requires-Dist: mcp>=1.6.0
Requires-Dist: python-dotenv>=1.0.0
Description-Content-Type: text/markdown

# Bilibili MCP Server

基于 `bilibili-api-python` 的 MCP (Model Context Protocol) 服务器，提供完整的 Bilibili API 工具调用能力。

## 特性

- **22个实用工具**，覆盖视频、用户、搜索、评论、排行榜、消息等核心功能
- 使用 **stdio** 传输方式，与 Claude Desktop 无缝集成
- 支持环境变量配置登录凭证，安全便捷
- 统一的响应格式，易于处理
- 完整的类型注解和参数验证

---

## 安装

### 方式一：从 PyPI 安装（推荐）

```bash
# 使用 pip 安装
pip install bilibili_mcp_python

# 或使用 uv 安装
uv pip install bilibili_mcp_python
```

### 方式二：从源码运行

```bash
# 克隆仓库
git clone https://github.com/YunGaoluo/bilibili-mcp-python.git
cd bilibili-mcp

# 使用 uv 安装依赖（推荐）
uv sync
source .venv/bin/activate  # Linux/Mac
# 或
.venv\Scripts\activate     # Windows

# 或使用 pip 安装
pip install -e .
```

---

## 配置

### 环境变量

复制 `.env.example` 为 `.env` 并填写：

```bash
# Bilibili 登录凭证（可选，用于需要登录的操作）
BILI_SESSDATA=your_sessdata
BILI_JCT=your_bili_jct
BILI_BUVID3=your_buvid3
```

**获取登录凭证：**
1. 登录 Bilibili 网页版
2. 打开浏览器开发者工具 (F12) → Application/应用 → Cookies
3. 复制 `SESSDATA`, `bili_jct`, `buvid3` 的值

### Claude Desktop 配置

在 Claude Desktop 配置文件 `claude_desktop_config.json` 中添加：

#### PyPI 安装方式的配置

```json
{
  "mcpServers": {
    "bilibili": {
      "command": "bilibili_mcp_python",
      "env": {
        "BILI_SESSDATA": "your_sessdata",
        "BILI_JCT": "your_bili_jct",
        "BILI_BUVID3": "your_buvid3"
      }
    }
  }
}
```

如果 `bilibili-mcp` 命令不在 PATH 中，可以使用完整路径：

```json
{
  "mcpServers": {
    "bilibili": {
      "command": "python",
      "args": ["-m", "bilibili_mcp_python.server"],
      "env": {
        "BILI_SESSDATA": "your_sessdata",
        "BILI_JCT": "your_bili_jct",
        "BILI_BUVID3": "your_buvid3"
      }
    }
  }
}
```

#### 源码运行方式的配置

```json
{
  "mcpServers": {
    "bilibili": {
      "command": "uv",
      "args": ["run", "bilibili_mcp_python"],
      "cwd": "/path/to/bilibili_mcp_python",
      "env": {
        "BILI_SESSDATA": "your_sessdata",
        "BILI_JCT": "your_bili_jct",
        "BILI_BUVID3": "your_buvid3"
      }
    }
  }
}
```

或使用 Python 直接运行：

```json
{
  "mcpServers": {
    "bilibili": {
      "command": "python",
      "args": ["-m", "bilibili_mcp_python.server"],
      "cwd": "/path/to/bilibili_mcp_python",
      "env": {
        "BILI_SESSDATA": "your_sessdata",
        "BILI_JCT": "your_bili_jct",
        "BILI_BUVID3": "your_buvid3"
      }
    }
  }
}
```

---

## 工具详解

### 视频模块（Video）

视频相关操作，包含信息获取、互动、弹幕等功能。

| 工具名 | 功能 | 关键参数 | 需登录 |
|--------|------|----------|--------|
| `bilibili_video_get_info` | 获取视频完整信息 | `bvid`: BV号 | 否 |
| `bilibili_video_interact` | 点赞/投币/收藏/三连 | `bvid`, `action`, `cancel` | **是** |
| `bilibili_video_get_download_info` | 获取下载链接和清晰度 | `bvid`, `page_num` | 否 |
| `bilibili_video_get_danmaku` | 获取弹幕列表 | `bvid`, `page_num`, `from_seg` | 否 |
| `bilibili_video_send_danmaku` | 发送弹幕 | `bvid`, `message`, `progress` | **是** |
| `bilibili_video_get_ai_conclusion` | 获取AI视频总结 | `bvid` | **是** |

**使用示例：**
```python
# 获取视频信息
bilibili_video_get_info(bvid="BV1xx411c7mD")

# 给视频三连
bilibili_video_interact(bvid="BV1xx411c7mD", action="triple")

# 发送弹幕（视频第10秒处）
bilibili_video_send_danmaku(
    bvid="BV1xx411c7mD",
    message="精彩！",
    progress=10000,  # 毫秒
    color="ff0000"
)
```

---

### 用户模块（User）

用户信息查询和关系管理。

| 工具名 | 功能 | 关键参数 | 需登录 |
|--------|------|----------|--------|
| `bilibili_user_get_info` | 获取用户完整信息 | `uid`: 用户UID | 否 |
| `bilibili_user_get_contents` | 获取用户发布的内容 | `uid`, `content_type` | 否 |
| `bilibili_user_modify_relation` | 关注/取关/拉黑/移除粉丝 | `uid`, `action` | **是** |
| `bilibili_user_get_followings` | 获取关注列表 | `uid`, `page_num` | **是** |
| `bilibili_user_get_followers` | 获取粉丝列表 | `uid`, `page_num` | **是** |

**`content_type` 类型说明：**
- `video` - 视频（支持关键词搜索）
- `article` - 专栏文章
- `album` - 相簿
- `bangumi` - 追番列表

**使用示例：**
```python
# 获取UP主信息
bilibili_user_get_info(uid=208259)

# 获取用户的所有视频
bilibili_user_get_contents(uid=208259, content_type="video")

# 关注用户
bilibili_user_modify_relation(uid=208259, action="follow")
```

---

### 搜索模块（Search）

全网内容搜索和热门发现。

| 工具名 | 功能 | 关键参数 | 需登录 |
|--------|------|----------|--------|
| `bilibili_search` | 统一搜索 | `keyword`, `search_type` | 否 |
| `bilibili_get_hot_search` | 获取热门搜索词 | 无 | 否 |

**`search_type` 类型说明：**
- `all` - 综合搜索
- `video` - 视频
- `user` - 用户
- `article` - 专栏
- `live` - 直播

**使用示例：**
```python
# 搜索视频
bilibili_search(keyword="Python教程", search_type="video")

# 搜索用户
bilibili_search(keyword="老番茄", search_type="user")

# 获取热搜榜
bilibili_get_hot_search()
```

---

### 评论模块（Comment）

视频、动态、专栏的评论管理。

| 工具名 | 功能 | 关键参数 | 需登录 |
|--------|------|----------|--------|
| `bilibili_comment_get` | 获取评论列表（懒加载） | `oid`, `type_`, `mode`, `offset` | 否 |
| `bilibili_comment_send` | 发送评论/回复 | `oid`, `text`, `root` | **是** |
| `bilibili_comment_operate` | 点赞/点踩/删除/获取子评论 | `oid`, `rpid`, `action` | **是** |

**`type_` 类型说明：**
- `video` - 视频（oid为aid）
- `dynamic` - 动态（oid为动态id）
- `article` - 专栏（oid为cv号）

**使用示例：**
```python
# 获取视频评论（首次）
bilibili_comment_get(oid=170001, type_="video", mode="main")

# 回复评论（root为评论ID）
bilibili_comment_send(
    oid=170001,
    type_="video",
    text="说得好！",
    root=12345678
)

# 点赞评论
bilibili_comment_operate(oid=170001, rpid=12345678, action="like")
```

---

### 排行榜模块（Rank）

各类排行榜和热门视频获取。

| 工具名 | 功能 | 关键参数 | 需登录 |
|--------|------|----------|--------|
| `bilibili_get_rank` | 获取分区排行榜 | `rank_type`, `day` | 否 |
| `bilibili_get_hot` | 获取热门视频 | `page`, `page_size` | 否 |

**`rank_type` 排行榜类型：**

| 类型值 | 说明 | 类型值 | 说明 |
|--------|------|--------|------|
| `all` | 全站榜 | `game` | 游戏 |
| `bangumi` | 番剧 | `music` | 音乐 |
| `movie` | 电影 | `douga` | 动画 |
| `documentary` | 纪录片 | `ent` | 娱乐 |
| `guochuang` | 国创 | `life` | 生活 |
| `technology` | 科技数码 | `food` | 美食 |
| `knowledge` | 知识 | `sports` | 运动 |
| `dance` | 舞蹈 | `kichiku` | 鬼畜 |
| `original` | 原创 | `rookie` | 新人 |
| ... | 还有更多 | | |

**使用示例：**
```python
# 获取全站排行榜
bilibili_get_rank(rank_type="all")

# 获取游戏区三日榜
bilibili_get_rank(rank_type="game", day=3)

# 获取热门视频
bilibili_get_hot(page=1, page_size=20)
```

---

### 消息会话模块（Session）

私信、互动消息和系统通知管理。

| 工具名 | 功能 | 关键参数 | 需登录 |
|--------|------|----------|--------|
| `bilibili_session_list` | 获取会话列表/聊天记录 | `talker_id`, `session_type` | **是** |
| `bilibili_session_send` | 发送私信 | `receiver_id`, `content` | **是** |
| `bilibili_session_interactions` | 获取互动消息 | `interaction_type` | **是** |
| `bilibili_session_notifications` | 获取通知/未读统计 | `notification_type` | **是** |

**`interaction_type` 互动类型：**
- `replies` - 收到的回复
- `likes` - 收到的赞
- `at` - @我的消息

**`notification_type` 通知类型：**
- `unread` - 未读消息统计
- `system` - 系统消息
- `settings` - 消息设置

**使用示例：**
```python
# 获取会话列表
bilibili_session_list()

# 获取与某用户的聊天记录
bilibili_session_list(talker_id=208259)

# 发送私信
bilibili_session_send(receiver_id=208259, content="你好！")

# 获取收到的赞
bilibili_session_interactions(interaction_type="likes")

# 获取未读消息数
bilibili_session_notifications(notification_type="unread")
```

---

## 响应格式

所有工具返回统一的 JSON 格式：

```json
{
  "success": true,
  "code": 0,
  "message": "ok",
  "data": { ... }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `success` | boolean | 是否成功 |
| `code` | int | 状态码，0表示成功 |
| `message` | string | 状态描述或错误信息 |
| `data` | any | 实际返回数据 |

---

## 工具权限速查

### 无需登录（只读操作）
- 视频信息、弹幕、下载链接
- 用户信息、用户公开内容
- 搜索、热搜、排行榜、热门视频
- 评论列表

### 需要登录（写入操作）
- 视频互动（点赞/投币/收藏/三连）
- 发送弹幕、获取AI总结
- 关注/取关/拉黑等用户关系操作
- 发送评论、评论互动
- 所有消息会话相关操作

---

## License

GPL-3.0
