AI导哈

自然观察API服务器

一个提供对iNaturalist API访问的模型上下文协议服务器，通过分类工具实现组织化访问，支持自动认证和类型安全。

  • by Pixelworlds
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 pixelworlds/inat-mcp-server

使用说明

iNaturalist MCP服务器v0.2.0


[！警告]> 开发状态通知

- The iNaturalist API calls are returning too much data currently causing most of the
- requests to be rejected and causing the MCP server's clients to become unstable.
- Not recommended for use yet.

模型上下文协议（MCP）服务器，通过有组织的、基于类别的工具提供对iNaturalist API的访问。为@richardstovall/inat typescript客户端v0.2.0构建，具有完全重写的架构。

特性

  • 自动身份验证：启动时自动处理OAuth和API令牌流
  • 基于类别的工具：每个主要API类别一个工具，以便更好地组织
  • 综合文档：丰富的提示和资源解释了所有可用的端点
  • 类型安全：具有正确错误处理的完整TypeScript实现
  • 许可证管理：自动令牌缓存和刷新处理

可用工具

服务器提供9个基于类别的工具，每个工具包含多个端点：

  1. 观察 -搜索、创建、更新和管理观察结果
  2. 分类单元 -搜索和检索分类信息
  3. 地点 -地理位置数据和地点管理
  4. 项目 -项目信息和管理
  5. 识别 -物种鉴定和建议
  6. 用户 -用户配置文件和帐户信息
  7. 评论 -对意见和其他内容的评论
  8. 搜索 -跨所有内容类型的通用搜索
  9. 旗帜 -内容标记和审核

每个工具都包括其可用方法、参数和使用示例的详细文档。

认证

服务器需要iNaturalist OAuth凭据，并自动处理完整的身份验证流程：

  1. OAuth令牌：使用资源所有者密码凭据流从以下位置获取访问令牌 https://www.inaturalist.org/oauth/token
  2. API代币：使用访问令牌从中检索永久API令牌 https://www.inaturalist.org/users/api_token
  3. 用户信息：从预加载用户信息 https://api.inaturalist.org/v1/users/me 为了上下文

所需凭据

  • client_id：您的iNaturalist OAuth应用程序客户端ID
  • client_secret：您的iNaturalist OAuth应用程序客户端密钥
  • username：您的iNaturalist用户名
  • password：您的iNaturalist密码

安装

# Install dependencies
yarn install

# Generate tools (analyzes v0.2.0 client structure)
yarn generate-tools

# Build the project
yarn build

用法

命令行

# Run with credentials
node dist/cli.js --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET --username YOUR_USERNAME --password YOUR_PASSWORD

# Environment variables
export INAT_CLIENT_ID="your_client_id"
export INAT_CLIENT_SECRET="your_client_secret"
export INAT_USERNAME="your_username"
export INAT_PASSWORD="your_password"
node dist/cli.js

克劳德桌面

添加到您的Claude Desktop配置中：

{
  "mcpServers": {
    "inaturalist": {
      "command": "node",
      "args": ["/path/to/inat-mcp-server/dist/cli.js"],
      "env": {
        "INAT_CLIENT_ID": "your_client_id",
        "INAT_CLIENT_SECRET": "your_client_secret",
        "INAT_USERNAME": "your_username",
        "INAT_PASSWORD": "your_password"
      }
    }
  }
}

示例用法

搜索观察结果

{
  "name": "observations",
  "arguments": {
    "method": "observation_search",
    "parameters": {
      "q": "monarch butterfly",
      "place_id": 97394,
      "per_page": 10
    }
  }
}

获取分类信息

{
  "name": "taxa",
  "arguments": {
    "method": "taxa_search",
    "parameters": {
      "q": "Danaus plexippus",
      "rank": "species"
    }
  }
}

搜索地点

{
  "name": "places",
  "arguments": {
    "method": "places_search",
    "parameters": {
      "q": "Yellowstone National Park"
    }
  }
}

文档

服务器通过以下方式提供丰富的文档：

  • 鼓励：使用各类工具的详细指南
  • 资源：所有终结点的API参考文档
  • 例子：常见任务的实际使用示例

通过MCP协议访问文档：

  • 列表提示： prompts/list
  • 获取提示： prompts/get 其名称类似于“观察指南”
  • 列出资源： resources/list
  • 读取资源： resources/read URI类似于“docs://observations"

发展

项目结构

src/
├── generate-tools.ts    # Tool generator for v0.2.0 client
├── server.ts           # Main MCP server implementation
├── cli.ts              # Command-line interface
└── prebuild.ts         # Build validation

dist/                   # Compiled JavaScript output

构建过程

  1. 工具生成：分析v0.2.0客户端以提取所有可用方法
  2. TypeScript编译：以适当的模块分辨率编译为JavaScript
  3. 验证：确保所有必需的文件和依赖项都存在

身份验证流程

服务器实现了一个复杂的三步身份验证过程：

  1. OAuth身份验证：邮寄至 https://www.inaturalist.org/oauth/token 使用用户名/密码
  2. API令牌检索：获取 https://www.inaturalist.org/users/api_token 使用承载访问令牌
  3. 用户信息：获取 https://api.inaturalist.org/v1/users/me 使用API令牌作为上下文

所有身份验证都会在服务器初始化期间自动进行。如果身份验证失败，服务器将优雅地回退到只读模式，可以访问所有公共数据。

错误处理

  • 身份验证失败：当凭据无效或身份验证失败时，优雅地回退到只读模式
  • 网络问题：强大的错误处理，带有详细的错误消息，用于调试
  • API错误：带有HTTP状态代码和有用上下文的结构化错误响应
  • 端点分辨率：自动检测OAuth与API调用的正确终结点

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

贡献

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

支持

关于以下问题：

相关 MCP