inaturalist-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ranfang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+# iNaturalist MCP
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js 18+](https://img.shields.io/badge/node.js-18+-green.svg)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-6-blue.svg)](https://www.typescriptlang.org/)
+
+Read-only Model Context Protocol server for the public iNaturalist API.
+
+## Tools
+
+- `search_observations`: Search public observations by taxon, place, user, date, location, or text.
+- `get_observation`: Fetch one observation by ID.
+- `search_taxa`: Search taxa by scientific name, common name, rank, or iconic taxon.
+- `get_taxon`: Fetch one taxon by ID.
+- `get_observation_species_counts`: Fetch species counts for observation filters.
+
+## Install
+
+From npm:
+
+```bash
+npm install -g inaturalist-mcp
+```
+
+From source:
+
+```bash
+npm install
+npm run build
+```
+
+## Run
+
+Stdio transport, for local MCP clients:
+
+```bash
+inaturalist-mcp
+```
+
+HTTP transport, for deployed MCP clients:
+
+```bash
+node dist/index.js --transport http --host 127.0.0.1 --port 8890
+```
+
+You can also configure HTTP mode with environment variables:
+
+```bash
+MCP_TRANSPORT=http HOST=0.0.0.0 PORT=8890 node dist/index.js
+```
+
+The HTTP MCP endpoint is:
+
+```text
+http://127.0.0.1:8890/mcp
+```
+
+## Client Config
+
+Example stdio MCP client configuration:
+
+Using npm:
+
+```json
+{
+  "mcpServers": {
+    "inaturalist": {
+      "command": "npx",
+      "args": ["-y", "inaturalist-mcp"]
+    }
+  }
+}
+```
+
+Using a local checkout:
+
+```json
+{
+  "mcpServers": {
+    "inaturalist": {
+      "command": "node",
+      "args": ["/path/to/inaturalist-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+Example Streamable HTTP MCP client URL:
+
+```text
+http://127.0.0.1:8890/mcp
+```
+
+## Notes
+
+This server only wraps public read endpoints and does not require OAuth. Authenticated write operations are intentionally out of scope for the initial version.

package/dist/index.js

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+import { randomUUID } from "node:crypto";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import * as z from "zod/v4";
+const API_BASE_URL = "https://api.inaturalist.org/v1";
+const USER_AGENT = "inaturalist-mcp/1.0 (https://github.com/ufo2243/inaturalist-mcp)";
+class INaturalistApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+    }
+}
+function buildUrl(path, params = {}) {
+    const url = new URL(`${API_BASE_URL}/${path.replace(/^\/+/, "")}`);
+    for (const [key, value] of Object.entries(params)) {
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                if (item !== undefined && item !== null && item !== "") {
+                    url.searchParams.append(key, String(item));
+                }
+            }
+            continue;
+        }
+        if (value !== undefined && value !== null && value !== "") {
+            url.searchParams.set(key, String(value));
+        }
+    }
+    return url;
+}
+async function getJson(path, params = {}) {
+    const url = buildUrl(path, params);
+    const response = await fetch(url, {
+        headers: {
+            Accept: "application/json",
+            "User-Agent": USER_AGENT,
+        },
+    });
+    if (!response.ok) {
+        const body = await response.text();
+        throw new INaturalistApiError(`iNaturalist API request failed with HTTP ${response.status}`, response.status, body.slice(0, 1000));
+    }
+    return response.json();
+}
+function toolResult(data) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+        structuredContent: data,
+    };
+}
+function errorResult(error) {
+    const message = error instanceof INaturalistApiError
+        ? `${error.message}\n\n${error.body}`
+        : error instanceof Error
+            ? error.message
+            : String(error);
+    return {
+        isError: true,
+        content: [
+            {
+                type: "text",
+                text: message,
+            },
+        ],
+    };
+}
+const paginationSchema = {
+    page: z.number().int().min(1).optional().describe("Page number. Defaults to 1."),
+    per_page: z
+        .number()
+        .int()
+        .min(1)
+        .max(50)
+        .optional()
+        .describe("Results per page, capped at 50. Defaults to iNaturalist's API default."),
+};
+function createServer() {
+    const server = new McpServer({
+        name: "inaturalist-mcp",
+        version: "1.0.0",
+    });
+    server.registerTool("search_observations", {
+        description: "Search public iNaturalist observations by taxon, place, user, date, location, or free text.",
+        inputSchema: {
+            q: z.string().optional().describe("Free-text search query."),
+            taxon_id: z.number().int().positive().optional().describe("iNaturalist taxon ID."),
+            place_id: z.number().int().positive().optional().describe("iNaturalist place ID."),
+            user_id: z.string().optional().describe("iNaturalist username or user ID."),
+            lat: z.number().min(-90).max(90).optional().describe("Latitude for geo search."),
+            lng: z.number().min(-180).max(180).optional().describe("Longitude for geo search."),
+            radius: z.number().positive().optional().describe("Radius in kilometers when lat/lng are provided."),
+            d1: z.string().optional().describe("Observed date lower bound, YYYY-MM-DD."),
+            d2: z.string().optional().describe("Observed date upper bound, YYYY-MM-DD."),
+            observed_on: z.string().optional().describe("Exact observed date, YYYY-MM-DD."),
+            quality_grade: z
+                .enum(["casual", "needs_id", "research"])
+                .optional()
+                .describe("Observation quality grade."),
+            order_by: z
+                .enum(["created_at", "observed_on", "species_guess", "votes", "id"])
+                .optional()
+                .describe("Sort field."),
+            order: z.enum(["asc", "desc"]).optional().describe("Sort direction."),
+            ...paginationSchema,
+        },
+    }, async (args) => {
+        try {
+            return toolResult(await getJson("observations", args));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    server.registerTool("get_observation", {
+        description: "Get one public iNaturalist observation by observation ID.",
+        inputSchema: {
+            id: z.number().int().positive().describe("iNaturalist observation ID."),
+        },
+    }, async ({ id }) => {
+        try {
+            return toolResult(await getJson(`observations/${id}`));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    server.registerTool("search_taxa", {
+        description: "Search iNaturalist taxa by name, common name, rank, or iconic taxon.",
+        inputSchema: {
+            q: z.string().optional().describe("Taxon name or common name query."),
+            rank: z
+                .enum(["kingdom", "phylum", "class", "order", "family", "genus", "species", "subspecies"])
+                .optional()
+                .describe("Taxonomic rank filter."),
+            iconic_taxa: z
+                .string()
+                .optional()
+                .describe("Comma-separated iconic taxa, e.g. Aves,Mammalia,Plantae."),
+            locale: z.string().optional().describe("Locale for common names, e.g. en, zh-CN."),
+            ...paginationSchema,
+        },
+    }, async (args) => {
+        try {
+            return toolResult(await getJson("taxa", args));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    server.registerTool("get_taxon", {
+        description: "Get one iNaturalist taxon by taxon ID.",
+        inputSchema: {
+            id: z.number().int().positive().describe("iNaturalist taxon ID."),
+            locale: z.string().optional().describe("Locale for common names, e.g. en, zh-CN."),
+        },
+    }, async ({ id, locale }) => {
+        try {
+            return toolResult(await getJson(`taxa/${id}`, { locale }));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    server.registerTool("get_observation_species_counts", {
+        description: "Get species counts from public iNaturalist observations for a place, taxon, user, date range, or location.",
+        inputSchema: {
+            taxon_id: z.number().int().positive().optional().describe("iNaturalist taxon ID."),
+            place_id: z.number().int().positive().optional().describe("iNaturalist place ID."),
+            user_id: z.string().optional().describe("iNaturalist username or user ID."),
+            lat: z.number().min(-90).max(90).optional().describe("Latitude for geo search."),
+            lng: z.number().min(-180).max(180).optional().describe("Longitude for geo search."),
+            radius: z.number().positive().optional().describe("Radius in kilometers when lat/lng are provided."),
+            d1: z.string().optional().describe("Observed date lower bound, YYYY-MM-DD."),
+            d2: z.string().optional().describe("Observed date upper bound, YYYY-MM-DD."),
+            locale: z.string().optional().describe("Locale for common names, e.g. en, zh-CN."),
+            ...paginationSchema,
+        },
+    }, async (args) => {
+        try {
+            return toolResult(await getJson("observations/species_counts", args));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    return server;
+}
+function getArgValue(name) {
+    const index = process.argv.indexOf(name);
+    return index >= 0 ? process.argv[index + 1] : undefined;
+}
+function getTransportMode() {
+    const value = getArgValue("--transport") ?? process.env.MCP_TRANSPORT ?? "stdio";
+    if (value === "stdio" || value === "http") {
+        return value;
+    }
+    throw new Error(`Unsupported transport "${value}". Use "stdio" or "http".`);
+}
+function getPort() {
+    const value = getArgValue("--port") ?? process.env.PORT ?? "3000";
+    const port = Number(value);
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+        throw new Error(`Invalid port "${value}".`);
+    }
+    return port;
+}
+function getHost() {
+    return getArgValue("--host") ?? process.env.HOST ?? "127.0.0.1";
+}
+async function runStdio() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("iNaturalist MCP server running on stdio");
+}
+async function runHttp() {
+    const host = getHost();
+    const port = getPort();
+    const app = createMcpExpressApp({ host });
+    const transports = {};
+    app.post("/mcp", async (req, res) => {
+        const sessionId = req.headers["mcp-session-id"];
+        try {
+            let transport;
+            if (typeof sessionId === "string" && transports[sessionId]) {
+                transport = transports[sessionId];
+            }
+            else if (!sessionId && isInitializeRequest(req.body)) {
+                transport = new StreamableHTTPServerTransport({
+                    sessionIdGenerator: () => randomUUID(),
+                    onsessioninitialized: (newSessionId) => {
+                        transports[newSessionId] = transport;
+                    },
+                });
+                transport.onclose = () => {
+                    const closedSessionId = transport.sessionId;
+                    if (closedSessionId) {
+                        delete transports[closedSessionId];
+                    }
+                };
+                const server = createServer();
+                await server.connect(transport);
+            }
+            else {
+                res.status(400).json({
+                    jsonrpc: "2.0",
+                    error: {
+                        code: -32000,
+                        message: "Bad Request: missing session ID or initialize request",
+                    },
+                    id: null,
+                });
+                return;
+            }
+            await transport.handleRequest(req, res, req.body);
+        }
+        catch (error) {
+            console.error("Error handling MCP request:", error);
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: "2.0",
+                    error: {
+                        code: -32603,
+                        message: "Internal server error",
+                    },
+                    id: null,
+                });
+            }
+        }
+    });
+    app.get("/mcp", async (req, res) => {
+        const sessionId = req.headers["mcp-session-id"];
+        if (typeof sessionId !== "string" || !transports[sessionId]) {
+            res.status(400).send("Invalid or missing session ID");
+            return;
+        }
+        await transports[sessionId].handleRequest(req, res);
+    });
+    app.delete("/mcp", async (req, res) => {
+        const sessionId = req.headers["mcp-session-id"];
+        if (typeof sessionId !== "string" || !transports[sessionId]) {
+            res.status(400).send("Invalid or missing session ID");
+            return;
+        }
+        await transports[sessionId].handleRequest(req, res);
+    });
+    const httpServer = app.listen(port, host, () => {
+        console.error(`iNaturalist MCP server listening at http://${host}:${port}/mcp`);
+    });
+    process.on("SIGINT", async () => {
+        for (const transport of Object.values(transports)) {
+            await transport.close();
+        }
+        httpServer.close(() => process.exit(0));
+    });
+}
+async function main() {
+    if (getTransportMode() === "http") {
+        await runHttp();
+        return;
+    }
+    await runStdio();
+}
+main().catch((error) => {
+    console.error("Server error:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "inaturalist-mcp",
+  "version": "1.0.0",
+  "description": "Read-only Model Context Protocol server for the iNaturalist API.",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "inaturalist-mcp": "dist/index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ufo2243/inaturalist-mcp.git"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "inaturalist",
+    "biodiversity"
+  ],
+  "author": "ranfang",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/ufo2243/inaturalist-mcp/issues"
+  },
+  "homepage": "https://github.com/ufo2243/inaturalist-mcp#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "express": "^5.2.1",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.6.0",
+    "typescript": "^6.0.3"
+  }
+}