gbif MCP

GBIF MCP服务器

模型上下文协议（MCP）服务器，提供对全球生物多样性信息设施（GBIF）API的程序访问。

概述

该MCP服务器使AI助手和应用程序能够通过模型上下文协议与GBIF的广泛生物多样性数据进行交互。GBIF提供来自世界各地的数亿种物种发生记录、分类信息和生物多样性研究数据。

什么是GBIF？

这 全球生物多样性信息设施 是一个国际网络和数据基础设施，提供对生物多样性数据的开放访问。GBIF API提供对以下内容的编程访问：

• 物种数据：分类信息、物种发现和名称匹配实用程序
• 事件记录：物种观察和标本索引记录
• 数据集：关于已发布数据集及其来源的信息
• 组织：关于出版组织和机构的数据
• 地图：生物多样性数据可视化
• 文学：引用GBIF数据集的同行评审论文
• 词汇：生物多样性数据的标准化术语

什么是MCP？

这 模型上下文协议 是一个开放协议，规范了人工智能应用程序与外部数据源和工具的交互方式。该服务器实现了MCP，使克劳德等人工智能助手可以访问GBIF的生物多样性数据。

快速开始

# 1. Clone and build
git clone https://github.com/tyson-swetnam/gbif-mcp.git
cd gbif-mcp
npm install
npm run build

# 2. Add to Claude Code
claude mcp add gbif node "$(pwd)/build/index.js"

# 3. Test it
claude chat "Search GBIF for Panthera leo occurrences in Kenya"

或者，对于Claude Desktop，请添加 claude_desktop_config.json:

{
  "mcpServers": {
    "gbif": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/gbif-mcp/build/index.js"]
    }
  }
}

特性

此MCP服务器提供对关键GBIF API端点的访问，并提供全面的参数文档：

• API种：搜索物种，获取分类信息，并匹配科学名称
• 发生API：使用40+高级过滤器查询物种发生记录
• 注册API：访问有关数据集和发布组织的信息
• 地图API：生成生物多样性数据的可视化
• 文献API：搜索引用GBIF数据的研究论文
• 验证程序API：执行数据质量检查

综合参数说明

每个刀具参数包括：

• 详细说明 目的和用途
• 真实世界的例子 使用实际的GBIF数据（例如，“示例：猫科动物为212”）
• 有效值列表 用于具有人类可读描述的枚举
• 范围限制 以及数据类型信息
• GBIF API文档链接 供进一步参考

这使得AI助手能够轻松构建准确的查询，而无需猜测参数格式。

响应大小限制

为了确保与AI上下文窗口的兼容性，此服务器实现了自动响应大小限制：

• 最大响应大小：250KB（可通过以下方式配置 RESPONSE_MAX_SIZE_KB)
• 警告阈值：200KB（记录优化警告）
• 智能截断：较大的响应会自动截断，并提供有用的分页指导

配置

通过环境变量控制响应限制：

RESPONSE_MAX_SIZE_KB=250              # Maximum response size
RESPONSE_WARN_SIZE_KB=200             # Warning threshold
RESPONSE_ENABLE_TRUNCATION=true       # Enable smart truncation
RESPONSE_ENABLE_SIZE_LOGGING=true     # Log size metrics

截断响应

当响应超过大小限制时，您将收到：

{
  "truncated": true,
  "originalSize": "1.2MB",
  "returnedSize": "248KB",
  "metadata": {
    "totalCount": 1000,
    "returnedCount": 23
  },
  "pagination": {
    "suggestion": "Use limit=20 with offset=0, then offset=20, offset=40...",
    "example": { "taxonKey": 212, "limit": 20, "offset": 0 }
  },
  "data": { ... }
}

安装

来源

# Clone the repository
git clone https://github.com/tyson-swetnam/gbif-mcp.git
cd gbif-mcp

# Install dependencies
npm install

# Build the server
npm run build

来自NPM（发布时）

npm install -g gbif-mcp

使用Docker

# Clone the repository
git clone https://github.com/tyson-swetnam/gbif-mcp.git
cd gbif-mcp

# Build the Docker image
docker build -t gbif-mcp:latest .

# Or use Docker Compose
docker-compose build

Docker镜像使用Alpine Linux的多阶段构建，占用空间小（~150MB）。

配置

选项1:克劳德桌面应用程序

将服务器添加到Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gbif": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/gbif-mcp/build/index.js"],
      "env": {
        "GBIF_USERNAME": "your-username",
        "GBIF_PASSWORD": "your-password"
      }
    }
  }
}

重要：替换 /ABSOLUTE/PATH/TO 带有克隆存储库的完整路径。

示例 （macOS）：

{
  "mcpServers": {
    "gbif": {
      "command": "node",
      "args": ["/Users/yourname/projects/gbif-mcp/build/index.js"]
    }
  }
}

示例 （Windows）：

{
  "mcpServers": {
    "gbif": {
      "command": "node",
      "args": ["C:\\Users\\YourName\\projects\\gbif-mcp\\build\\index.js"]
    }
  }
}

更新配置后：

1. 保存文件
2. 重新启动克劳德桌面
3. 寻找🔌 用于验证MCP服务器是否已连接的图标

选项2:Claude代码命令行界面

如果你正在使用 克劳德代码，您可以使用CLI添加MCP服务器：

# Navigate to your gbif-mcp directory
cd /path/to/gbif-mcp

# Add the MCP server
claude mcp add gbif node build/index.js

# Or with environment variables for authenticated endpoints
claude mcp add gbif node build/index.js --env GBIF_USERNAME=your-username --env GBIF_PASSWORD=your-password

验证安装：

# List all MCP servers
claude mcp list

# Test the connection
claude mcp test gbif

选项3：Docker容器

在Docker容器中运行MCP服务器，以进行隔离、可重复的部署：

Docker快速入门

# Build the image
docker build -t gbif-mcp:latest .

# Run the container (stdio mode for MCP)
docker run -i gbif-mcp:latest

Claude桌面与Docker

更新您的Claude Desktop配置以使用Docker容器：

macOS/Linux:

{
  "mcpServers": {
    "gbif": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "GBIF_USERNAME=your-username",
        "-e", "GBIF_PASSWORD=your-password",
        "gbif-mcp:latest"
      ]
    }
  }
}

视窗:

{
  "mcpServers": {
    "gbif": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "GBIF_USERNAME=your-username",
        "-e", "GBIF_PASSWORD=your-password",
        "gbif-mcp:latest"
      ]
    }
  }
}

使用Docker的Claude代码CLI

# Add the Docker-based MCP server
claude mcp add gbif docker run -i --rm gbif-mcp:latest

# With environment variables
claude mcp add gbif docker run -i --rm \
  -e GBIF_USERNAME=your-username \
  -e GBIF_PASSWORD=your-password \
  gbif-mcp:latest

Docker Compose

为了便于管理，请使用Docker Compose：

# Start the service
docker-compose up -d gbif-mcp

# View logs
docker-compose logs -f gbif-mcp

# Stop the service
docker-compose down

编辑 docker-compose.yml 要配置环境变量，请执行以下操作：

environment:
  - GBIF_USERNAME=${GBIF_USERNAME}
  - GBIF_PASSWORD=${GBIF_PASSWORD}
  - LOG_LEVEL=debug  # Change log level

然后在Claude Desktop配置中使用：

{
  "mcpServers": {
    "gbif": {
      "command": "docker",
      "args": ["compose", "run", "--rm", "gbif-mcp"]
    }
  }
}

Docker环境变量

将环境变量传递给Docker容器：

# Using -e flags
docker run -i --rm \
  -e GBIF_USERNAME=myusername \
  -e GBIF_PASSWORD=mypassword \
  -e LOG_LEVEL=debug \
  -e CACHE_ENABLED=true \
  gbif-mcp:latest

# Using an env file
echo "GBIF_USERNAME=myusername" > .env.docker
echo "GBIF_PASSWORD=mypassword" >> .env.docker
docker run -i --rm --env-file .env.docker gbif-mcp:latest

Docker镜像详细信息

• 基本图像：Node.js 20 Alpine Linux
• 尺寸：~150MB（多阶段构建）
• 用户：以非root用户身份运行（uid 1001）
• 安全：只读根文件系统，无新权限
• 健康检查：内置健康监测

选项4：其他MCP客户端

对于其他MCP兼容客户端（Codex、Gemini CLI等），请按照其MCP服务器设置文档将服务器添加到客户端的配置文件中：

通用MCP配置格式:

{
  "mcpServers": {
    "gbif": {
      "command": "node",
      "args": ["/absolute/path/to/gbif-mcp/build/index.js"],
      "env": {
        "GBIF_USERNAME": "optional-username",
        "GBIF_PASSWORD": "optional-password"
      }
    }
  }
}

环境变量

创建 .env 项目根目录中的文件用于本地开发（可选）：

# GBIF API Credentials (optional - only needed for downloads and authenticated endpoints)
GBIF_USERNAME=your-gbif-username
GBIF_PASSWORD=your-gbif-password

# GBIF API Configuration (optional - defaults shown)
GBIF_BASE_URL=https://api.gbif.org/v1
GBIF_USER_AGENT=GBIF-MCP-Server/1.0.0
GBIF_TIMEOUT=30000

# Rate Limiting (optional - defaults shown)
RATE_LIMIT_MAX_REQUESTS=100
RATE_LIMIT_CONCURRENT=10

# Caching (optional - defaults shown)
CACHE_ENABLED=true
CACHE_MAX_SIZE=100
CACHE_TTL=3600000

# Logging (optional - defaults shown)
LOG_LEVEL=info
LOG_FORMAT=json

备注：大多数GBIF API终结点不需要身份验证。仅以下情况需要凭据：

• 请求事件下载
• 访问私有数据集
• 发布数据（目前尚未实施）

验证安装

配置后，验证服务器是否正常工作：

在克劳德桌面中：

1. 打开克劳德桌面
2. 寻找🔌 界面中的MCP图标
3. 尝试查询：“在GBIF中搜索肯尼亚的Panthera leo事件”

在Claude Code CLI中：

# List available tools
claude mcp tools gbif

# Test a simple query
claude chat "Use the gbif MCP server to search for Panthera leo"

手动测试（stdio）：

# Build and test the server directly
npm run build
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node build/index.js

可用工具

服务器提供以下MCP工具用于与GBIF数据交互：

物种工具

• gbif_species_search -使用高级过滤搜索物种
• gbif_species_get -获取特定物种的详细信息
• gbif_species_suggest -获取物种名称建议以进行自动补全
• gbif_species_match -将物种名称与GBIF分类进行模糊匹配
• gbif_species_children -获得一个分类单元的直接分类子级
• gbif_species_parents -获取完整的分类路径
• gbif_species_synonyms -获取同义词和替代名称
• gbif_species_vernacular_names -获取多种语言的通用名称
• gbif_species_descriptions -获取物种的文本描述
• gbif_species_distributions -获取地理分布信息
• gbif_species_media -获取图像、声音和视频

事件工具

• gbif_occurrence_search -使用40+个筛选参数搜索事件记录
• gbif_occurrence_get -获取单个事件的完整详细信息
• gbif_occurrence_count -快速计数，无需检索完整记录
• gbif_occurrence_verbatim -获取原始未处理的事件数据
• gbif_occurrence_download_request -请求大数据集下载（需要身份验证）
• gbif_occurrence_download_status -检查下载状态
• gbif_occurrence_download_predicate_builder -构建下载过滤器

所有工具都包含全面的参数描述和示例。使用 claude mcp tools gbif 查看完整列表。

使用示例

配置后，您可以通过AI助手使用MCP服务器：

物种查询

• “印度虎发生记录检索”
• “查找Quercus robur物种的分类信息”
• “意大利蜜蜂在不同语言中的通用名称是什么？”
• “给我看看非洲狮的完整分类”
• “查找学名Felis leo的所有同义词”

事件查询

• “2023年，加利福尼亚州记录了多少次鸟类观测？”
• “寻找1900年以前采集的兰花标本”
• “向我展示国家公园的事件记录和照片”
• “巴西濒危物种观测搜索”

数据管理

• “列出自然历史博物馆发布的数据集”
• “给我看最近引用GBIF关于传粉昆虫数据的论文”
• “发布前验证此生物多样性数据集”

故障排除

服务器未连接

克劳德桌面：

1. 检查配置文件路径是否正确
2. 验证您使用的是绝对路径（而不是相对路径，如 ~/ 或 ./)
3. 确保生成目录存在： ls /path/to/gbif-mcp/build/index.js
4. 检查克劳德桌面日志：

- macOS： ~/Library/Logs/Claude/ - 窗户： %APPDATA%\Claude\logs\

克劳德代码CLI：

# Check server status
claude mcp status gbif

# View logs
claude mcp logs gbif

# Remove and re-add
claude mcp remove gbif
claude mcp add gbif node /absolute/path/to/gbif-mcp/build/index.js

构建错误

# Clean and rebuild
rm -rf build node_modules
npm install
npm run build

# Check for TypeScript errors
npm run build -- --noEmit

Docker问题

图像构建失败：

# Clean Docker cache and rebuild
docker system prune -a
docker build --no-cache -t gbif-mcp:latest .

# Check Docker version (requires 20.10+)
docker --version

容器无法启动：

# Check container logs
docker logs 

# Run with debug logging
docker run -i --rm -e LOG_LEVEL=debug gbif-mcp:latest

# Test container health
docker run --rm gbif-mcp:latest node -e "console.log('test')"

权限问题：

# Ensure Docker daemon is running
docker ps

# Check if user has Docker permissions (Linux)
sudo usermod -aG docker $USER
# Log out and back in for group changes to take effect

环境变量不起作用：

# Verify environment variables are passed
docker run -i --rm gbif-mcp:latest node -e "console.log(process.env.GBIF_USERNAME)"

# Use --env-file for multiple variables
docker run -i --rm --env-file .env.docker gbif-mcp:latest

MCP与Docker的通信问题：

• 确保您正在使用 -i stdio通信的（交互式）标志
• 使用 --rm 执行后自动删除容器
• 不使用 -d （分离）模式-MCP需要stdio连接
• 检查MCP配置中的命令是否完全匹配： docker run -i --rm gbif-mcp:latest

身份验证问题

如果你在下载时遇到401个错误：

1. 在以下网址验证您的GBIF凭据 GBIF.org
2. 检查环境变量是否设置正确
3. 创建 .env 项目根目录中包含您的凭据的文件
4. 注意：大多数端点不需要身份验证，只有下载需要

速率限制

如果您受到费率限制：

1. 减少查询频率
2. 在大型搜索之前使用计数端点
3. 考虑缓存结果
4. 对大型数据集使用引用下载，而不是分页

Node.js版本

确保你使用的是Node.js 18或更高版本：

node --version  # Should be v18.0.0 or higher

API覆盖范围

此MCP服务器实现以下GBIF API部分：

• ✅ API种
• ✅ 发生API
• ✅ 注册API
• ✅ 地图API
• ✅ 文献API
• ✅ 词汇API
• ✅ 验证程序API

发展

# Run in development mode
npm run dev

# Run tests
npm test

# Lint code
npm run lint

资源

• GBIF API文档
• GBIF网站
• 模型上下文协议文档
• GBIF API基本URL

贡献

欢迎投稿！请随时提交问题或拉取请求。

1. 克隆该仓库
2. 创建功能分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add some amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

许可证

MIT许可证

致谢

该项目使用GBIF API提供生物多样性数据访问。GBIF由政府资助，并维护一个稳定的API版本1，并提供向后兼容性保证。

支持

• GBIF API问题：
• GBIF社区论坛： discuse.gbif.org
• MCP问题：在此存储库中打开问题