Skip to main content
Glama
mcp-server-birdstats

mcp-server-birdstats

mcp-server-birdstats

MCP server that exposes BirdWeather and eBird analysis context for code-execution and chat clients.

What This Server Provides

This server focuses on three read-only tools and one analysis prompt:

  • get_system_prompt

  • get_birdweather_api

  • get_ebird_api

  • check-bird prompt

The tools are intentionally optimized for low-token defaults:

  • Default mode is summary.

  • Full payload access requires mode="full" and confirmLargePayload=true.

  • Tool failures return structured errors (status, retryable, suggestion, message) to help clients self-correct.

Related MCP server: Birding Planner

Requirements

  • Node.js 18+

  • npm

Install

npm install
npm run build

Run

stdio (default)

npm run start

or explicitly:

npm run start:stdio

Streamable HTTP

MCP_TRANSPORT=streamable-http \
MCP_HTTP_HOST=127.0.0.1 \
MCP_HTTP_PORT=3000 \
MCP_HTTP_PATH=/mcp \
npm run start

Optional hardening:

  • MCP_ALLOWED_ORIGINS=http://localhost,http://127.0.0.1:3000

If an Origin header is present and not allowed, the server returns 403.

Docker

Build:

docker build -t mcp-server-birdstats .

Run in stdio mode:

docker run --rm -it mcp-server-birdstats

Run in Streamable HTTP mode:

docker run --rm -p 3000:3000 \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_HTTP_HOST=0.0.0.0 \
  -e MCP_HTTP_PORT=3000 \
  -e MCP_HTTP_PATH=/mcp \
  mcp-server-birdstats

Test

npm test

The behavior suite covers:

  • initialize lifecycle

  • tools/list

  • successful tools/call

  • failing tools/call with structured error assertions

  • both stdio and streamable-http transports

Provider API Notes

The included birdweather_api.json and ebird_api.json files are local OpenAPI snapshots consumed by the tools above.

License

MIT

Appendix: MCP in Practice (Code Execution, Tool Scale, and Safety)

Last updated: 2026-03-23

Why This Appendix Exists

Model Context Protocol (MCP) is still one of the most useful interoperability layers for tools and agents. The tradeoff is that large MCP servers can expose many tools, and naive tool-calling can flood context windows with schemas, tool chatter, and irrelevant call traces.

In practice, "more tools" is not always "better outcomes." Tool surface area must be paired with execution patterns that keep token use bounded and behavior predictable.

The Shift to Code Execution / Code Mode

Recent workflows increasingly move complex orchestration out of chat context and into code execution loops. This reduces repetitive schema tokens and makes tool usage auditable and testable.

Core reading:

For users who want reproducible and lower-noise MCP usage, start with a codemode-oriented setup:

Practical caveat: even with strong setup, model behavior can still be inconsistent across providers and versions. Keep retries, guardrails, and deterministic fallbacks in place.

Peter Steinberger-Style Wrapper Workflow

A high-leverage pattern is wrapping MCP servers into callable code interfaces and task-focused CLIs instead of exposing every raw tool to the model at all times.

Reference tooling:

What Works Best With Which MCP Clients

  • Claude Code / Codex / Cursor: strong for direct MCP workflows, but still benefit from narrow tool surfaces.

  • Code-execution wrappers (TypeScript/Python CLIs): better when tool count is high or task chains are multi-step.

  • Hosted chat clients with weaker MCP controls: often safer via pre-wrapped CLIs or gateway tools.

This ecosystem changes rapidly. If you are reading this now, parts of this guidance may already be out of date.

Prompt Injection: Risks, Impact, and Mitigations

Prompt injection remains an open security problem for tool-using agents. It is manageable, but not solved.

Primary risks:

  • Malicious instructions hidden in tool output or remote content.

  • Secret exfiltration and unauthorized external calls.

  • Unsafe state changes (destructive file/system/API actions).

Consequences:

  • Data leakage, account compromise, financial loss, and integrity failures.

Mitigation baseline:

  • Least privilege for credentials and tool scopes.

  • Allowlist destinations and enforce egress controls.

  • Strict input validation and schema enforcement.

  • Human confirmation for destructive/high-risk actions.

  • Sandboxed execution with resource/time limits.

  • Structured logging, audit trails, and replayable runs.

  • Output filtering/redaction before model re-ingestion.

Treat every tool output as untrusted input unless explicitly verified.

Available Tools

3 tools
get_birdweather_apiRead BirdWeather API SchemaA
Read-onlyIdempotent

Use this tool to inspect the BirdWeather OpenAPI contract used by this server. Required inputs: none. Defaults: mode='summary', maxPaths=25, optional pathPrefix filter. Set mode='full' with confirmLargePayload=true for full schema. Side effects: none (read-only local file access). Cost note: full schema is large; summary is preferred for planning.

Inputs: mode, confirmLargePayload, maxPaths, pathPrefix.

get_ebird_apiRead eBird API SchemaA
Read-onlyIdempotent

Use this tool to inspect the eBird OpenAPI contract used by this server. Required inputs: none. Defaults: mode='summary', maxPaths=25, optional pathPrefix filter. Set mode='full' with confirmLargePayload=true for full schema. Side effects: none (read-only local file access). Cost note: full schema is large; use summary first.

Inputs: mode, confirmLargePayload, maxPaths, pathPrefix.

get_system_promptRead BirdStats System PromptA
Read-onlyIdempotent

Use this tool when you need operational instructions for BirdStats analysis behavior. Required inputs: none. Defaults: mode='summary', previewLineCount=12. Set mode='full' with confirmLargePayload=true to return full prompt text. Side effects: none (read-only local file access). Cost note: full mode can consume significant tokens.

Inputs: mode, confirmLargePayload, previewLineCount.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: inspecting the BirdWeather API contract, inspecting the eBird API contract, and retrieving the system prompt for operational instructions. There is no overlap in functionality or ambiguity between these three tools.

    Naming Consistency5/5

    All tool names follow a consistent 'get_' prefix pattern (get_birdweather_api, get_ebird_api, get_system_prompt), with clear and descriptive nouns. This uniformity makes the tool set predictable and easy to understand.

    Tool Count3/5

    With only three tools, the server feels thin for a domain that appears to involve bird statistics analysis. While the tools cover API inspection and prompt retrieval, the lack of actual data retrieval or analysis tools suggests an incomplete surface for the implied purpose.

    Completeness2/5

    The tool set is severely incomplete for a bird statistics server. It only provides meta-tools for inspecting APIs and prompts, with no tools to fetch or analyze bird data from BirdWeather or eBird. This creates significant gaps that will hinder agents from performing meaningful tasks in the domain.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Integrates the eBird API with Claude to query bird observation data, including recent sightings, rare bird reports, contributor statistics, hotspot locations, and taxonomy information through natural language.
      6
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An AI-powered birding companion that connects Claude to eBird and Xeno-canto APIs, enabling personalized birding with life list tracking, route-based hotspot discovery, and recording enrichment.
      28
      2
      MIT