Inat MCP Server

iNaturalist MCP服务器v0.2.0

\[！警告\]> 开发状态通知 ``diff - 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服务器：在此存储库中打开一个问题
• 自然主义者API：检查 iNaturalist API文档
• TypeScript客户端：检查 @richardstoval/inat打字客户端 包裹