iNaturalist MCP

• Setup
  • Local
  • Remote
• Development
• Building
• Support
• Contributing

iNaturalist MCP server that provides access to the iNaturalist API via the Model Context Protocol.

Exposes a search_taxa tool that searches for organisms by common or scientific name and returns taxonomic details, common names, photos, and Wikipedia links.

Setup

This can be run in Local CLI mode or Remote server mode.

Local

In CLI mode using uv.

View Config - Local uv

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "inaturalist": {
      "type": "local",
      "command": ["uvx", "inaturalist-mcp"],
      "enabled": true
    }
  }
}

In CLI mode using Python pip.

pip install inaturalist-mcp

View Config - Local Python

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "inaturalist": {
      "type": "local",
      "command": ["inaturalist-mcp"],
      "enabled": true
    }
  }
}

Remote

With Docker run.

docker run --rm -p 80:8000 ghcr.io/cssnr/inaturalist-mcp:latest

With Docker Compose.

services:
  app:
    image: ghcr.io/cssnr/inaturalist-mcp:latest
    ports:
      - '80:8000'

With Python from source.

uv sync
uv run uvicorn inaturalist_mcp.server:app --app-dir src --host 0.0.0.0 --port 8000

View Config - Remote

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "inaturalist": {
      "type": "remote",
      "url": "http://localhost/mcp",
      "enabled": true
    }
  }
}

Note: Set the url to the host you are running the server on.

For a Docker Swarm + Traefik example see the docker-compose-swarm.yaml.

For a Portainer Deploy workflow see the .github/workflows/deploy.yaml.

Development

Sync project.

uv sync

Run local server.

run cli

Run remote server (live reload).

run dev

Point your client to: http://localhost:8000/mcp

Run remote Docker Compose (live reload).

run compose

Point your client to: http://localhost/mcp

You can set the PORT environment variable.

Building

Docker Image

To build and test the docker image run.

bash build.sh
docker compose up

Point your client to: http://localhost/mcp

Python Package

This builds the bdist and wheel, if you have a use for it...

run build

Support

If you run into any issues or need help getting started, please do one of the following:

• Report an Issue: https://github.com/cssnr/inaturalist-mcp/issues
• Q&A Discussion: https://github.com/cssnr/inaturalist-mcp/discussions/categories/q-a
• Request a Feature: https://github.com/cssnr/inaturalist-mcp/issues/new?template=1-feature.yaml
• Chat with us on Discord: https://discord.gg/wXy6m2X8wY

Contributing

Please consider making a donation to support the development of this project and additional open source projects.

For a full list of current projects visit: https://cssnr.github.io/