内容
<div align="center">
<h1>cyanheads/chembl-mcp-server</h1>
<p><b>关联化合物与蛋白质靶点，评估生物活性（IC50/Ki/EC50），并通过MCP查询药物机制和适应症。支持标准输入输出或流式HTTP。</b>
<div>7种工具（+1种可选）• 2种资源</div>
</p>
</div>
<div align="center">
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/chembl-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/chembl-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/)
</div>
<div align="center">
[](https://github.com/cyanheads/chembl-mcp-server/releases/latest/download/chembl-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=chembl-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvY2hlbWJsLW1jcC1zZXJ2ZXIiXX0=) [](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22chembl-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fchembl-mcp-server%22%5D%7D)
[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
</div>
---
## 工具
八种工具 — 五种用于ChEMBL化合物/靶点/生物活性表面，加上三种用于SQL分析的工具（第三种是可选的）：
| 工具 | 描述 |
|:---|:---|
| `chembl_search_molecules` | 按名称/ChEMBL ID/InChIKey查找化合物，或从SMILES进行结构搜索（精确\|相似性\|子结构）。 |
| `chembl_get_bioactivities` | 旗舰工具：化合物↔靶点桥梁，提供生物活性测量值，按`pchembl_value`排序。大型数据集会溢出到画布中。 |
| `chembl_search_targets` | 将蛋白质/基因符号/UniProt登录号解析为ChEMBL靶点ID。 |
| `chembl_get_drug_info` | 药物药理学 — 作用机制、分子靶点、作用类型、首次批准年份和临床适应症。 |
| `chembl_get_assay` | 生物活性行的测定出处 — 类型、靶点、生物体和ChEMBL的1-9置信度评分。 |
| `chembl_dataframe_query` | 在溢出的生物活性行上运行只读SQL `SELECT` — 排序、分组、去重、聚合整个数据集。 |
| `chembl_dataframe_describe` | 列出画布上暂存的表和列，以便在查询前编写正确的SQL。 |
| `chembl_dataframe_drop` | 从画布中删除已命名的暂存表。可选，启用方式为`CHEMBL_DATAFRAME_DROP_ENABLED=true` — 当关闭时，从`tools/list`中缺失，因为TTL已经回收了暂存表。 |
### `chembl_search_molecules`
化合物的发现入口点。
- 默认`search_type=name`匹配药物名称、别名、ChEMBL ID和InChIKeys。
- 通过`search_type`进行结构搜索：`exact`（精确匹配）、`similarity`（相似度≥阈值）或`substructure`（包含查询结构）— 提供`structure`作为SMILES。
- `similarity_threshold`是一个40-100的整数（默认70；ChEMBL拒绝低于40的值）。
- `max_phase_min`限制名称搜索到化合物处于或高于最大临床阶段（例如`4`表示仅限已上市药物）。
- 每行都带有`max_phase` — 廉价的药物可用性信号（4 = 已上市，0 = 研究）— 以及分子量、AlogP、Lipinski五规则违规和QED；结构搜索还返回相似度百分比。
### `chembl_get_bioactivities`
旗舰工具和服务器存在的原因 — 整理的化合物↔靶点↔测定链接。
- 提供`molecule_chembl_id`（靶点反解码/选择性）或`target_chembl_id`（先导物发现）中的一个；两者或两者都不提供是`missing_filter`错误。
- 按`standard_type`（IC50 / Ki / EC50 / ...）、最小效能`pchembl_value_min`、`assay_type`和`organism`过滤；行按`pchembl_value`排序（-log10摩尔效能）。
- **排名陷阱：** `pchembl_value`仅在一种`standard_type`内可比较 — 设置过滤器，因为混合IC50和Ki是科学错误。
- 数值在服务边界处从上游JSON字符串强制转换为`number | null`；缺失的效能读取为`null`，而非`0`。
- 一个热门靶点带有数万个测量值：当数据集超过内联预览时，它会**溢出**到DataCanvas表（`bioactivities`）中，您可以使用`chembl_dataframe_query`进行诚实的聚合。
### `chembl_search_targets`
将蛋白质解析为ChEMBL靶点ID，后续工具需要该ID。
- 提供至少一个`accession`（UniProt，例如`P00533`）、`gene_symbol`（例如`EGFR`）或`query`（自由文本名称）；进一步限制`organism`和`target_type`。
- UniProt登录号是最精确的输入 — 从`uniprot` / `protein`服务器链接。
- 每行都带有靶点类型、生物体和组件UniProt登录号+基因符号（从ChEMBL的嵌套组件同义词展平）。
- 将`target_chembl_id`链接到`chembl_get_bioactivities`。
### `chembl_get_drug_info`
化合物的药物药理学 — 与`openfda`服务器的标签/不良事件视图不同。
- 提供`molecule_chembl_id`（来自`chembl_search_molecules`）。
- 返回作用机制、分子靶点、作用类型（抑制剂/激动剂/...）、首次批准年份和临床适应症，以及每个适应症达到的最大阶段。
- 由分子+机制+适应症通过`Promise.allSettled`组合，因此缺少机制或适应症列表会降级为空数组，而不是使调用失败。
- 机制的`target_chembl_id`链接到`chembl_get_bioactivities`以获取命中相同靶点的化合物。
### `chembl_get_assay`
生物活性行的测定出处 — 调用它来判断两个测量值是否可比较，然后将它们一起排名。
- 提供来自`chembl_get_bioactivities`行的`assay_chembl_id`。
- 返回描述、测定类型（结合/功能性/ADMET/毒性）、测定的靶点、生物体和ChEMBL的1-9置信度评分（9 = 蛋白质靶点的直接测定，较低 = 同源或间接）。
### `chembl_dataframe_query` / `chembl_dataframe_describe` / `chembl_dataframe_drop`
在溢出的`bioactivities`表上进行SQL分析。查询溢出时，工具返回`canvas_id`；将其传递给`chembl_dataframe_query`进行排序、分组、去重和聚合整个数据集 — 标准DuckDB SQL。
- **只读。** `chembl_dataframe_query`接受单个`SELECT`；写入、DDL和非SELECT语句被框架SQL门拒绝。引用返回的暂存表（`bioactivities`），并先使用`chembl_dataframe_describe`发现其列。
- 溢出的表包含完整的`Activity`行 — 18列，包括归一化的`standard_*` / `pchembl_value`字段（按这些字段排序）和原始上游`type` / `value` / `units` / `relation`（仅审核）。在此计算聚合，而不是在内联预览上。
- `chembl_dataframe_drop`是唯一破坏性的工具，并且是**可选的**（`CHEMBL_DATAFRAME_DROP_ENABLED=true`）— 关闭时，从`tools/list`中缺失，因为每个表和画布的TTL已经回收了暂存表。
## 资源和提示
| 类型 | 名称 | 描述 |
|:---|:---|:---|
| 资源 | `chembl://molecule/{chemblId}` | 按ChEMBL ID的分子记录 — 与`chembl_search_molecules`行具有相同的形状（ID、名称、结构、属性、最大临床阶段）。 |
| 资源 | `chembl://target/{chemblId}` | 按ChEMBL靶点ID的靶点记录 — 首选名称、类型、生物体和组件UniProt登录号+基因符号。 |
所有资源数据也可以通过工具访问，因此仅限工具的MCP客户端不会失去任何功能 — 资源是可注入上下文的便捷镜像。`{chemblId}`根据`CHEMBL\d+`模式验证。没有提示；规范的工作流程是代理直接组合的短工具链，跨服务器链指南作为服务器级`instructions`提供。
## 特性
基于[`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)：
- 声明式工具和资源定义 — 每个基元的单个文件，框架处理注册和验证。
- 统一错误处理 — 处理程序抛出，框架捕获、分类和格式化。
- 类型错误合约，带有恢复提示（`missing_filter`，`missing_input`，`canvas_disabled`）。
- 可插拔身份验证（`none`，`jwt`，`oauth`）和可交换存储后端。
- 带有可选OpenTelemetry跟踪的结构化日志记录。
- STDIO和流式HTTP传输。
ChEMBL特定：
- ChEMBL REST数据API的单一无密钥上游客户端 — Django样式的过滤URL构建器，`page_meta`分页，`withRetry`-包装的获取+解析。
- 在服务边界处将字符串转换为`number | null`数值（缺失的效能变为`null`，而非`0` — 科学数据保真度规则）。
- 双向生物活性：一个工具提供化合物→靶点和靶点→化合物，按`pchembl_value`排序。
- 结构搜索（精确/相似性/子结构）合并在一个发现工具下，通过`search_type`枚举。
- 旗舰工具的数据画布溢出：数万行活动集流式传输到DuckDB表，可通过`chembl_dataframe_query`查询。
代理友好输出：
- 每个响应的出处 — 总计数、应用过滤器回声和溢出通知，以便代理知道预览是完整集还是画布表的切片。
- 截断披露 — 限制搜索结果报告`shown` / `cap` / `totalCount`，以便页面永远不会被误认为是完整集。
- 类型化、可恢复的错误 — `missing_filter` / `missing_input` / `canvas_disabled`带有恢复提示，因此调用者无需解析散文即可纠正调用。
## 入门
ChEMBL是无密钥的 — 不需要API密钥或帐户。
将以下内容添加到MCP客户端配置文件中：
```json
{
"mcpServers": {
"chembl-mcp-server": {
"type": "stdio",
"command": "bunx",
"args": ["@cyanheads/chembl-mcp-server@latest"],
"env": {
"MCP_TRANSPORT_TYPE": "stdio",
"MCP_LOG_LEVEL": "info"
}
}
}
}
```
或使用npx（不需要Bun）：
```json
{
"mcpServers": {
"chembl-mcp-server": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@cyanheads/chembl-mcp-server@latest"],
"env": {
"MCP_TRANSPORT_TYPE": "stdio",
"MCP_LOG_LEVEL": "info"
}
}
}
}
```
或使用Docker：
```json
{
"mcpServers": {
"chembl-mcp-server": {
"type": "stdio",
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/chembl-mcp-server:latest"]
}
}
}
```
对于流式HTTP，设置传输并启动服务器：
```sh
MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# 服务器监听 http://localhost:3010/mcp
```
要解锁分析SQL路径（`bioactivities`溢出和`chembl_dataframe_*`工具），请在`env`中添加`"CANVAS_PROVIDER_TYPE": "duckdb"`。
### 先决条件
- [Bun v1.3.0](https://bun.sh/) 或更高版本（或Node.js v24+）。
- 可选：设置`CANVAS_PROVIDER_TYPE=duckdb`以启用大型生物活性集的数据画布SQL路径。
### 安装
1. **克隆仓库：**
```sh
git clone https://github.com/cyanheads/chembl-mcp-server.git
```
2. **进入目录：**
```sh
cd chembl-mcp-server
```
3. **安装依赖项：**
```sh
bun install
```
4. **配置环境：**
```sh
cp .env.example .env
# 编辑.env以覆盖任何默认值（均为可选）
```
## 配置
所有配置在启动时通过`src/config/server-config.ts`中的Zod模式验证。ChEMBL是无密钥的，因此所有变量都是可选的。
| 变量 | 描述 | 默认值 |
|:---|:---|:---|
| `CANVAS_PROVIDER_TYPE` | 设置为`duckdb`以启用生物活性溢出和`chembl_dataframe_*` SQL工具。 | `none` |
| `CHEMBL_API_BASE_URL` | ChEMBL REST数据API的基准URL。覆盖私有镜像或固定主机。 | `https://www.ebi.ac.uk/chembl/api/data` |
| `CHEMBL_REQUEST_TIMEOUT_MS` | 每个请求的超时时间（毫秒），用于上游ChEMBL获取。 | `30000` |
| `CHEMBL_MAX_PAGE_SIZE` | 溢出时ChEMBL每页的最大数量（最多1000）。 | `1000` |
| `CHEMBL_DEFAULT_LIMIT` | 调用者省略时的默认结果限制。 | `25` |
| `CHEMBL_DATAFRAME_DROP_ENABLED` | 注册可选的`chembl_dataframe_drop`工具（当关闭时，从`tools/list`中缺失）。 | `false` |
| `MCP_TRANSPORT_TYPE` | 传输：`stdio`或`http`。 | `stdio` |
| `MCP_HTTP_PORT` | HTTP服务器的端口。 | `3010` |
| `MCP_AUTH_MODE` | 身份验证模式：`none`，`jwt`或`oauth`。 | `none` |
| `MCP_LOG_LEVEL` | 日志级别（RFC 5424）。 | `info` |
| `LOGS_DIR` | 日志文件目录（仅限Node.js）。 | `<项目根>/logs` |
| `OTEL_ENABLED` | 启用[OpenTelemetry仪表盘](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry)。 | `false` |
参见[.env.example](./.env.example)获取完整的可选覆盖列表。
## 运行服务器
### 本地开发
- **构建和运行：
```sh
# 一次性构建
bun run rebuild
# 运行已构建的服务器
bun run start:stdio
# 或
bun run start:http
```
- **运行检查和测试：
```sh
bun run devcheck # 校验、格式化、类型检查、安全性和更改日志同步
bun run test # Vitest测试套件
bun run lint:mcp # 验证MCP定义是否符合规范
```
### Docker
```sh
docker build -t chembl-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=stdio chembl-mcp-server
```
Dockerfile默认使用HTTP传输、无状态会话模式和日志记录到`/var/log/chembl-mcp-server`。OpenTelemetry对等依赖项默认安装 — 通过`--build-arg OTEL_ENABLED=false`构建以省略它们。完全解析的`@duckdb`本机二进制文件从构建阶段复制，因此`CANVAS_PROVIDER_TYPE=duckdb`在运行时有效。
## 项目结构
| 目录 | 用途 |
|:---|:---|
| `src/index.ts` | `createApp()`入口点 — 注册工具/资源并初始化ChEMBL服务+可选画布。 |
| `src/config` | 服务器特定的环境变量解析和验证，使用Zod。 |
| `src/mcp-server/tools/definitions` | 工具定义（`*.tool.ts`）。五种ChEMBL工具+三种`chembl_dataframe_*`画布工具。 |
| `src/mcp-server/resources/definitions` | 资源定义（`*.resource.ts`）。分子和靶点记录镜像。 |
| `src/services/chembl` | 单个ChEMBL上游客户端 — URL构建器、分页、数值强制转换、嵌套结构展平、活动页流式传输。 |
| `src/services/canvas-accessor.ts` | `DataCanvas`的可选持有者，在`createApp({ setup })`中连接。 |
| `tests/` | 镜像`src/`的单元和集成测试。 |
## 开发指南
参见[CLAUDE.md/AGENTS.md](./CLAUDE.md)获取开发指南和架构规则。简而言之：
- 处理程序抛出，框架捕获 — 工具逻辑中没有`try/catch`。
- 使用`ctx.log`进行请求范围的日志记录，使用`ctx.state`进行租户范围的存储。
- 在`createApp()`数组中注册新的工具和资源。
- 包装ChEMBL API：验证原始数据 → 规范化为扁平域类型 → 返回输出模式；绝不伪造缺失字段（缺失的数值变为`null`，而非`0`）。
## 贡献
欢迎提交问题和拉取请求。在提交之前运行检查和测试：
```sh
bun run devcheck
bun run test
```
## 许可证
Apache-2.0 — 参见[LICENSE](./LICENSE)获取详细信息。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器