内容
# ANSES Ciqual MCP 服务器
<div align="center">
[](https://lobehub.com/mcp/zzgael-ciqual-mcp)
[](https://github.com/zzgael/ciqual-mcp/actions/workflows/tests.yml)
[](https://badge.fury.io/py/ciqual-mcp)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io/)
一个提供 SQL 访问功能的 MCP（模型上下文协议）服务器，用于访问 ANSES Ciqual 法国食品成分数据库。查询超过 3,000 种食品的营养数据，支持全文搜索。
<a href="https://glama.ai/mcp/servers/@zzgael/ciqual-mcp">
<img width="380" height="200" src="https://glama.ai/mcp/servers/@zzgael/ciqual-mcp/badge" alt="ANSES Ciqual 服务器 MCP 服务器" />
</a>
</div>
## 功能
- 🍎 **全面的数据库**：访问 3,185+ 种法国食品的营养数据
- 🔍 **SQL 接口**：使用标准 SQL 查询，具有完全的灵活性
- 🌍 **双语支持**：法语和英语食品名称
- 🔤 **模糊搜索**：内置全文搜索，容忍输入错误
- 📊 **60+ 种营养素**：包括维生素、矿物质、宏量营养素等详细成分
- 🔄 **自动更新**：每年从 ANSES 自动刷新数据（启动时检查）
- 🔒 **只读**：安全的查询，无数据修改风险
- 💾 **轻量级**：~10MB SQLite 数据库，高效索引
## 安装
### 通过 pip
```bash
pip install ciqual-mcp
```
### 通过 uvx（推荐）
```bash
uvx ciqual-mcp
```
### 从源码
```bash
git clone https://github.com/zzgael/ciqual-mcp.git
cd ciqual-mcp
pip install -e .
```
## MCP 客户端配置
### Claude Desktop
添加到您的 Claude Desktop 配置文件中：
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
**Linux**: `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"ciqual": {
"command": "uvx",
"args": ["ciqual-mcp"]
}
}
}
```
### Gemini CLI
添加到您的 Gemini CLI 配置文件 `~/.gemini/settings.json` 中：
```json
{
"mcpServers": {
"ciqual": {
"command": "uvx",
"args": ["ciqual-mcp"]
}
}
}
```
### Codex CLI
添加到您的 Codex CLI 配置文件 `~/.codex/config.toml` 中：
```toml
[mcp_servers.ciqual]
command = "uvx"
args = ["ciqual-mcp"]
```
## 使用
### 作为 MCP 服务器
服务器实现了模型上下文协议，并公开了一个 `query` 函数：
```bash
# 独立启动服务器（用于测试）
ciqual-mcp
```
### 直接 Python 使用
```python
from ciqual_mcp.data_loader import initialize_database
# 初始化/更新数据库
initialize_database()
# 然后直接使用 SQLite
import sqlite3
conn = sqlite3.connect("~/.ciqual/ciqual.db")
cursor = conn.execute("SELECT * FROM foods WHERE alim_nom_eng LIKE '%apple%'")
```
## API 文档
### MCP 函数：`query`
服务器公开了一个用于在 Ciqual 数据库上执行 SQL 查询的 `query` 函数。
#### 函数签名
```python
async def query(sql: str) -> list[dict]
```
#### 参数
- **`sql`** （字符串，必填）：要在数据库上执行的 SQL 查询
- 必须是 SELECT 或 WITH 查询（只读访问）
- 支持所有标准 SQLite SQL 语法
- 可以使用 JOIN、GROUP BY、ORDER BY 等
- 通过 `foods_fts` 表支持全文搜索
#### 返回值
- **`list[dict]`**：结果行的数组，其中每行是一个以列名为键的字典
- 如果没有结果匹配查询，则返回空列表
- 如果查询失败，则返回带有 `"error"` 键的错误字典
#### 错误处理
函数在以下情况下返回错误字典：
- 数据库未初始化：`{"error": "Database not initialized..."}`
- 尝试非 SELECT 查询：`{"error": "Only SELECT queries are allowed for safety."}`
- SQL 语法错误：`{"error": "SQL error: [details]"}`
- 表未找到：`{"error": "Table not found. Available tables: foods, nutrients, composition, foods_fts, food_groups"}`
#### MCP 环境中的示例用法
```json
{
"method": "query",
"params": {
"sql": "SELECT f.alim_nom_eng, n.const_nom_eng, c.teneur, n.unit FROM foods f JOIN composition c ON f.alim_code = c.alim_code JOIN nutrients n ON c.const_code = n.const_code WHERE f.alim_nom_eng LIKE '%apple%' AND n.const_code IN (328, 25000, 31000)"
}
}
```
#### 响应示例
```json
[
{
"alim_nom_eng": "Apple, raw",
"const_nom_eng": "Energy",
"teneur": 52.0,
"unit": "kcal/100g"
},
{
"alim_nom_eng": "Apple, raw",
"const_nom_eng": "Protein",
"teneur": 0.3,
"unit": "g/100g"
}
]
```
## 数据库架构
### 表
#### `foods` - 食品项目
- `alim_code` （INTEGER，主键）：唯一的食品标识符
- `alim_nom_fr` （TEXT）：法语名称
- `alim_nom_eng` （TEXT）：英语名称
- `alim_grp_code` （TEXT）：食品组代码
#### `nutrients` - 营养素定义
- `const_code` （INTEGER，主键）：唯一的营养素标识符
- `const_nom_fr` （TEXT）：法语名称
- `const_nom_eng` （TEXT）：英语名称
- `unit` （TEXT）：测量单位（g/100g，mg/100g 等）
#### `composition` - 营养价值
- `alim_code` （INTEGER）：食品标识符
- `const_code` （INTEGER）：营养素标识符
- `teneur` （REAL）：每 100g 的值
- `code_confiance` （TEXT）：置信度（A/B/C/D）
#### `foods_fts` - 全文搜索
用于法语/英语名称模糊匹配的虚拟表
### 常见营养素代码
| 类别 | 代码 | 营养素 | 单位 |
|----------|------|----------|------|
| **能量** | 327 | 能量 | kJ/100g |
| | 328 | 能量 | kcal/100g |
| **宏量营养素** | 25000 | 蛋白质 | g/100g |
| | 31000 | 碳水化合物 | g/100g |
| | 40000 | 脂肪 | g/100g |
| | 34100 | 纤维 | g/100g |
| | 32000 | 糖类 | g/100g |
| **矿物质** | 10110 | 钠 | mg/100g |
| | 10200 | 钙 | mg/100g |
| | 10260 | 铁 | mg/100g |
| | 10190 | 钾 | mg/100g |
| **维生素** | 55400 | 维生素 C | mg/100g |
| | 56400 | 维生素 D | µg/100g |
| | 51330 | 维生素 B12 | µg/100g |
## 示例查询
### 基本搜索
```sql
-- 按名称查找食品
SELECT * FROM foods WHERE alim_nom_eng LIKE '%orange%';
-- 模糊搜索（处理输入错误）
SELECT * FROM foods_fts WHERE foods_fts MATCH 'orang*';
```
### 营养查询
```sql
-- 获取橙子的维生素 C 含量
SELECT f.alim_nom_eng, c.teneur as vitamin_c_mg
FROM foods f
JOIN composition c ON f.alim_code = c.alim_code
WHERE f.alim_nom_eng LIKE '%orange%'
AND c.const_code = 55400;
-- 查找蛋白质含量最高的食品
SELECT f.alim_nom_eng, c.teneur as protein_g
FROM foods f
JOIN composition c ON f.alim_code = c.alim_code
WHERE c.const_code = 25000
ORDER BY c.teneur DESC
LIMIT 10;
-- 比较不同食品的宏量营养素
SELECT
f.alim_nom_eng as food,
MAX(CASE WHEN c.const_code = 25000 THEN c.teneur END) as protein_g,
MAX(CASE WHEN c.const_code = 31000 THEN c.teneur END) as carbs_g,
MAX(CASE WHEN c.const_code = 40000 THEN c.teneur END) as fat_g,
MAX(CASE WHEN c.const_code = 328 THEN c.teneur END) as calories_kcal
FROM foods f
JOIN composition c ON f.alim_code = c.alim_code
WHERE f.alim_nom_eng IN ('Apple, raw', 'Banana, raw', 'Orange, raw')
AND c.const_code IN (25000, 31000, 40000, 328)
GROUP BY f.alim_code, f.alim_nom_eng;
```
### 饮食限制
```sql
-- 查找低钠食品（<100mg/100g）
SELECT f.alim_nom_eng, c.teneur as sodium_mg
FROM foods f
JOIN composition c ON f.alim_code = c.alim_code
WHERE c.const_code = 10110
AND c.teneur < 100
ORDER BY c.teneur ASC;
-- 高纤维食品（>5g/100g）
SELECT f.alim_nom_eng, c.teneur as fiber_g
FROM foods f
JOIN composition c ON f.alim_code = c.alim_code
WHERE c.const_code = 34100
AND c.teneur > 5
ORDER BY c.teneur DESC;
```
## 数据源
数据来源于官方 ANSES Ciqual 数据库：
- 网站：https://ciqual.anses.fr/
- 数据门户：https://www.data.gouv.fr/fr/datasets/table-de-composition-nutritionnelle-des-aliments-ciqual/
数据库在服务器启动时每年自动更新（自 2020 年以来数据未变，因此每年更新足够）。
## 要求
- Python 3.9 或更高版本
- 50MB 可用磁盘空间（用于数据库）
- 互联网连接（用于初始数据下载）
## 许可证
MIT 许可证 - 参见 LICENSE 文件了解详情
## 贡献
欢迎贡献！请随时提交拉取请求。
## 开发
### 运行测试
```bash
# 安装开发依赖
pip install -e .
pip install pytest pytest-asyncio
# 运行单元测试
python -m pytest tests/test_server.py -v
# 运行功能测试（需要数据库）
python -m pytest tests/test_functional.py -v
```
## 故障排除
### 数据库未初始化
- 检查互联网连接
- 确保 `~/.ciqual/` 目录有写入权限
- 尝试手动初始化：`python -m ciqual_mcp.data_loader`
### XML 解析错误
- 工具自动处理损坏的 XML，带有恢复模式
- 如果问题仍然存在，请删除 `~/.ciqual/ciqual.db` 并重启
## 致谢
由 **Gael Debost** 开发，作为 GPT Workbench 的一部分，这是一个由 [Ideagency](https://ideagency.fr) 开发的多 LLM 接口，用于医学研究。
数据由 ANSES（Agence nationale de sécurité sanitaire de l'alimentation, de l'environnement et du travail）提供。
## 引用
如果您在研究中使用此工具，请引用：
```bibtex
@software{ciqual_mcp,
title = {ANSES Ciqual MCP Server},
author = {Gael Debost},
year = {2025},
url = {https://github.com/zzgael/ciqual-mcp}
}
```
