`search_observations`

Pack: inaturalist · Endpoint: https://gateway.pipeworx.io/inaturalist/mcp

Search citizen-science observations on iNaturalist. Filter by taxon name (e.g., “Pandion haliaetus” or “osprey”), place name (“California”), year, threatened status, or quality grade. Returns photographed sightings with coordinates, dates, and observer info. Pairs well with GBIF for cross-validation.

Parameters

Name	Type	Required	Description
`taxon_name`	string	no	Scientific or common species/taxon name
`place`	string	no	Place name (country, state, park). Auto-resolved to place_id.
`year`	number	no	Filter to a specific year
`threatened`	boolean	no	Restrict to IUCN-threatened taxa
`quality_grade`	string	no	casual \| needs_id \| research (default: research)
`per_page`	number	no	Results per page (1-200, default 20)

Example call

Arguments

{
  "taxon_name": "Pandion haliaetus",
  "place": "California",
  "quality_grade": "research"
}

curl

curl -X POST https://gateway.pipeworx.io/inaturalist/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_observations","arguments":{"taxon_name":"Pandion haliaetus","place":"California","quality_grade":"research"}}}'

TypeScript (@pipeworx/sdk)

import { Pipeworx } from '@pipeworx/sdk';
const pipeworx = new Pipeworx();

const result = await pipeworx.call('search_observations', {
  "taxon_name": "Pandion haliaetus",
  "place": "California",
  "quality_grade": "research"
});

More examples

{
  "taxon_name": "osprey",
  "year": 2023,
  "threatened": true,
  "per_page": 50
}

Response shape

Always returns: resolved, total_results, observations

Field	Type	Description
`resolved`	object	Resolved taxon and place IDs from input names
`total_results`	number	Total observation count matching filters
`observations`	array	Array of observation records

Full JSON Schema

{
  "type": "object",
  "properties": {
    "resolved": {
      "type": "object",
      "description": "Resolved taxon and place IDs from input names",
      "properties": {
        "taxon": {
          "type": "object",
          "properties": {
            "id": {
              "type": "number",
              "description": "iNaturalist taxon ID"
            },
            "name": {
              "type": "string",
              "description": "Taxon name"
            }
          }
        },
        "place": {
          "type": "object",
          "properties": {
            "id": {
              "type": "number",
              "description": "iNaturalist place ID"
            },
            "name": {
              "type": "string",
              "description": "Place name"
            }
          }
        }
      }
    },
    "total_results": {
      "type": "number",
      "description": "Total observation count matching filters"
    },
    "observations": {
      "type": "array",
      "description": "Array of observation records",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "description": "Observation ID"
          },
          "url": {
            "type": "string",
            "description": "iNaturalist observation URL"
          },
          "observed_on": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO date observed"
          },
          "place": {
            "type": [
              "string",
              "null"
            ],
            "description": "Place guess from observation"
          },
          "latitude": {
            "type": [
              "number",
              "null"
            ],
            "description": "Latitude coordinate"
          },
          "longitude": {
            "type": [
              "number",
              "null"
            ],
            "description": "Longitude coordinate"
          },
          "taxon": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "number",
                "description": "Taxon ID"
              },
              "scientific_name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Scientific name"
              },
              "common_name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Common name"
              },
              "rank": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Taxonomic rank"
              }
            }
          },
          "observer": {
            "type": [
              "string",
              "null"
            ],
            "description": "Observer login name"
          },
          "photo": {
            "type": [
              "string",
              "null"
            ],
            "description": "Photo URL"
          },
          "quality_grade": {
            "type": [
              "string",
              "null"
            ],
            "description": "Quality grade (casual, needs_id, research)"
          }
        }
      }
    }
  },
  "required": [
    "resolved",
    "total_results",
    "observations"
  ]
}

Connect

Add this to your MCP client config, or use one-click install buttons:

{
  "mcpServers": {
    "inaturalist": {
      "url": "https://gateway.pipeworx.io/inaturalist/mcp"
    }
  }
}

See Getting Started for client-specific install steps.

search_observations