Bio Qc MCP

FastQC和MultiQC MCP服务器

用于全面生物信息学质量控制分析的专业模型上下文协议（MCP）服务器。该服务器提供自动质量控制流程执行、HTML报告分析和测序数据的高级数据可视化。

   

BioQC-MCP Workflow

🚀 快速开始

# 1. Clone and setup
git clone https://github.com/Babajan-B/BioQC-MCP.git
cd fastqc-multiqc-mcp-server
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 2. Install prerequisites
brew install fastqc          # macOS
pip install multiqc

# 3. Test the server
./tests/test_mcp_server.sh

# 4. Configure in Claude/Cursor (see below)

______________________________________________________________________

📋 概述

此MCP服务器提供 10种专用工具 生物信息学质量控制：

关键能力：

• 自动化质量控制工作流程
• HTML报告解释
• 高级可视化（线条、条形图、散点图、热图、小提琴图、方框图等）
• 出版物质量图表生成
• 多样本分析和汇总
• 代码执行模式 -为复杂的工作流程节省50-90%的代币

______________________________________________________________________

📦 安装

先决条件

必修的：

• Python 3.8+
• FastQC
• MultiQC

安装命令：

# macOS
brew install fastqc
pip install multiqc

# Linux (Ubuntu/Debian)
sudo apt-get install fastqc
pip install multiqc

# Verify installation
fastqc --version
multiqc --version

设置

# Clone repository
git clone https://github.com/Babajan-B/BioQC-MCP.git
cd fastqc-multiqc-mcp-server

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install Python dependencies
pip install -r requirements.txt

# Verify setup
./tests/test_mcp_server.sh

______________________________________________________________________

⚙️ 配置

克劳德桌面版

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "fastqc-multiqc": {
      "command": "/FULL/PATH/TO/venv/bin/python3",
      "args": ["/FULL/PATH/TO/fastqc-multiqc-mcp-server/src/server.py"]
    }
  }
}

替换 /FULL/PATH/TO/ 使用您的实际安装路径。

保存后重新启动Claude Desktop。

光标IDE

选项1：快速设置

# Copy example config
mkdir -p ~/Library/Application\ Support/Cursor/User/globalStorage
cp examples/cursor-mcp-config.json ~/Library/Application\ Support/Cursor/User/globalStorage/mcp.json

# Edit the file and update paths to your installation
# Then restart Cursor (⌘Q and reopen)

选项2：手动设置

编辑或创建 ~/Library/Application Support/Cursor/User/globalStorage/mcp.json:

{
  "mcpServers": {
    "fastqc-multiqc": {
      "command": "/FULL/PATH/TO/venv/bin/python3",
      "args": ["/FULL/PATH/TO/fastqc-multiqc-mcp-server/src/server.py"],
      "env": {
        "PATH": "/usr/local/bin:/opt/homebrew/bin:${PATH}",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

重新启动游标 保存后（⌘Q并重新打开）。

验证： 打开Cursor AI聊天并询问： *“可用的MCP工具有哪些？”*

______________________________________________________________________

🧪 测试

自动验证

# Run all checks
./tests/test_mcp_server.sh

这验证了：

• Python环境
• 已安装依赖项
• FastQC/MultiQC可用
• 服务器语法有效

手动MCP协议测试

# Test MCP protocol compliance
python3 tests/test_server_manually.py

使用MCP检查器进行交互式测试

# Launch Inspector for interactive testing
./tests/launch_inspector.sh

导航至http://localhost:6274并配置：

• 命令： /FULL/PATH/TO/venv/bin/python3
• 论据： /FULL/PATH/TO/src/server.py
• 点击“连接”以交互方式测试工具

______________________________________________________________________

💡 使用示例

质量控制分析

"Run FastQC analysis on sample1.fastq and sample2.fastq"
"Check the quality of all FASTQ files in ~/data/sequencing/"
"Create a MultiQC report for samples in ~/results/"

报告分析

"Read the FastQC report at ~/results/sample_fastqc.html"
"What does the quality report say about adapter contamination?"
"Summarize the MultiQC report findings"

数据可视化

"Generate a line chart showing per-base quality scores"
"Create a bar chart comparing GC content across samples"
"Make a heatmap of quality metrics"

完成工作流程

"Analyze all FASTQ files in ~/data/, generate FastQC reports, 
create a MultiQC summary, and show me a chart of overall quality scores"

🆕 代码执行管道（令牌节省50-90%）

在中执行完整的工作流 单一工具调用 使用 run_qc_pipeline 工具：

# AI writes and executes this pipeline:
files = list_fastq_files('/Users/jaan/Desktop/Alaa')
print(f"Found {len(files)} FASTQ files")

# Process files
for f in files:
    result = run_fastqc([f['path']], output_dir='./qc_results')
    print(f"Analyzed: {f['name']}")

# Generate aggregate report
multiqc = run_multiqc('./qc_results', output_dir='./report')
print(f"MultiQC report: {multiqc['report']}")

# Return structured result
result = {
    "files_analyzed": len(files),
    "report_path": multiqc['report']
}

管道中的可用功能：

• list_fastq_files(directory) -查找FASTQ文件
• run_fastqc(files, output_dir) -执行FastQC
• run_multiqc(input_dir, output_dir) -生成MultiQC
• parse_fastqc_summary(fastqc_dir) -提取指标
• generate_chart(chart_type, data, title) -创建可视化

好处（基于实际测试）：

看 skills/ 可重用管道模板的目录。

🛠️ 故障排除

工具未显示在Claude/Cursor中

1. 验证配置文件中的路径

   # Check Python path
   which python3  # After activating venv

   # Check server path
   ls -la src/server.py

1. 重新运行验证

   ./tests/test_mcp_server.sh

1. 检查日志

- 克劳德：检查开发人员控制台 - 光标：视图>开发人员>切换开发人员工具>控制台

未找到FastQC/MultiQC

# Verify installation
which fastqc
which multiqc

# If not found, install
brew install fastqc  # macOS
pip install multiqc

# Check PATH in config
# Add to config JSON:
"env": {
  "PATH": "/usr/local/bin:/opt/homebrew/bin:${PATH}"
}

服务器无法启动

# Check dependencies
pip install -r requirements.txt

# Test server directly
source venv/bin/activate
python3 src/server.py
# Should show MCP protocol output

# Check syntax
python3 -m py_compile src/server.py

权限问题

# Make scripts executable
chmod +x tests/*.sh
chmod +x src/server.py

______________________________________________________________________

📂 项目结构

fastqc-multiqc-mcp-server/
├── src/
│   ├── __init__.py
│   └── server.py              # Main MCP server
├── tests/                      # Testing utilities
│   ├── test_mcp_server.sh     # Automated verification
│   ├── test_server_manually.py# MCP protocol test
│   ├── test_real_fastqc.sh    # Real data test
│   └── launch_inspector.sh    # MCP Inspector launcher
├── examples/                   # Configuration examples
│   └── cursor-mcp-config.json
├── docs/                       # Additional documentation
│   ├── TESTING_WITH_INSPECTOR.md
│   ├── TESTING_COMPLETE.md
│   ├── DEPLOYMENT_CHECKLIST.md
│   └── COMPARISON_BIOINFOMCP.md
├── requirements.txt            # Python dependencies
├── CHANGELOG.md                # Version history
├── LICENSE                     # MIT License
└── README.md                   # This file

______________________________________________________________________

🔧 技术规格

MCP协议： 2024-11-05\ Python版本： 3.8+\ 服务器版本： 2.0.0

依赖关系：

• mcp>=1.0.0（模型上下文协议）
• pydantic>=2.0.0（数据验证）
• matplotlib>=3.8.0（可视化）
• 海运>=0.13.0（统计图形）
• plotly>=5.18.0（交互式图表）
• pandas>=2.1.0（数据操作）
• numpy>=1.24.0（数值计算）

外部工具：

• FastQC（质量控制）
• MultiQC（报告聚合）

支持的文件格式：

• .fast、.fq（未压缩）
• .fq.gz（gzip压缩）

______________________________________________________________________

🎯 特性

质量控制管道

• ✅ 单项和批量FASTQ分析
• ✅ 多样本聚合
• ✅ 自动文件发现
• ✅ 线程执行支持
• ✅ 所有标准测序格式

报告分析

• ✅ HTML报告解析
• ✅ 结构化数据提取
• ✅ 质量指标解释
• ✅ 表格和图表数据提取
• ✅ 无需浏览器

可视化

• ✅ 20+图表类型
• ✅ 出版物质量输出
• ✅ 自定义样式和主题
• ✅ 多种导出格式
• ✅ 交互式图表（Plotly）

______________________________________________________________________

📊 经过测试和验证

• ✅ 符合MCP协议2024-11-05
• ✅ 使用FASTQ文件进行测试
• ✅ 克劳德桌面集成（2025年12月）
• ✅ 光标IDE就绪
• ✅ MCP检查员已验证
• ✅ 所有10个工具均正常工作
• ✅ 生产就绪

______________________________________________________________________

🚀 部署

通过GitHub分享

1. 在GitHub上创建存储库
2. 推送代码：

   git remote add origin https://github.com/Babajan-B/BioQC-MCP.git
   git branch -M main
   git push -u origin main

1. 添加主题： mcp-server, bioinformatics, fastqc, quality-control

用户安装：

git clone https://github.com/Babajan-B/BioQC-MCP.git
cd fastqc-multiqc-mcp-server
./tests/test_mcp_server.sh  # Verify setup
# Then configure in Claude/Cursor

______________________________________________________________________

📄 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

______________________________________________________________________

🤝 贡献

欢迎投稿！拜托：

1. 复刻仓库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

______________________________________________________________________

📧 支持

• 问题：GitHub问题
• 电子邮件: bioinformatics.bb@gmail.com
• 文档：参见 docs/ 附加指南目录

______________________________________________________________________

🎓 资源

• 模型上下文协议
• FastQC文档
• MultiQC文档
• MCP服务器示例

______________________________________________________________________

版本： 2.0.0\ 状态： 生产就绪\ 最后更新时间： 2025年12月