`search_observations`

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

Search citizen-science wildlife observations on iNaturalist — ANY organism: plants, fungi, insects, birds, mammals, reptiles, amphibians. This is the tool for “sightings/observations of in in ”. Filter by taxon name (scientific or common, e.g. “Leucanthemum vulgare”/“oxeye daisy”, “Pandion haliaetus”/“osprey”), place name (“Yukon”, “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"
            },
            "rank": {
              "type": [
                "string",
                "null"
              ],
              "description": "Taxonomic rank of the resolved taxon (species, genus, family, ...)"
            }
          }
        },
        "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