The mcp-server-birdstats is a read-only MCP server that exposes BirdWeather and eBird API schemas plus operational analysis instructions for bird data workflows. All operations access only local bundled files — no external API calls or writes.
Inspect BirdWeather API Schema (get_birdweather_api): Browse the BirdWeather OpenAPI contract with summary (up to 25 paths by default) or full schema views, with optional pathPrefix filtering and large payload confirmation.
Inspect eBird API Schema (get_ebird_api): Browse the eBird OpenAPI contract with the same controls — summary/full modes, path count limits (up to 200), and prefix filtering.
Retrieve System Prompt (get_system_prompt): Get operational instructions and behavior guidelines for BirdStats analysis — summary (first 12 lines) by default, or full text with mode='full' and confirmLargePayload=true.
check-bird Analysis Prompt: A built-in prompt for guided bird observation analysis drawing on both API schemas.
Token-optimized by design: All tools default to mode='summary'; full payloads require explicit confirmLargePayload=true.
Structured error responses: Errors include status, retryable, suggestion, and message fields to help clients self-correct.
Flexible deployment: Supports stdio and streamable-http transports, with Docker support and optional CORS hardening.
Allows users to access repository functionality, including cloning the repository and handling issues for feature requests and bug reports.
Facilitates installation and execution of the MCP plugin through NPX commands.
Enables data-driven visualizations using React artifacts for displaying bird detection data and statistics.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-server-birdstats what's my rarest detection this month?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server that exposes BirdWeather and eBird analysis context for code-execution and chat clients.
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
Node.js 18+
npm
npm install
npm run buildnpm run startor explicitly:
npm run start:stdioMCP_TRANSPORT=streamable-http \
MCP_HTTP_HOST=127.0.0.1 \
MCP_HTTP_PORT=3000 \
MCP_HTTP_PATH=/mcp \
npm run startOptional 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.
Build:
docker build -t mcp-server-birdstats .Run in stdio mode:
docker run --rm -it mcp-server-birdstatsRun 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-birdstatsnpm testThe behavior suite covers:
initialize lifecycle
tools/list
successful tools/call
failing tools/call with structured error assertions
both stdio and streamable-http transports
The included birdweather_api.json and ebird_api.json files are local OpenAPI snapshots consumed by the tools above.
BirdWeather reference: https://app.birdweather.com/api/v1/docs
eBird reference hub: https://support.ebird.org/en/support/solutions/articles/48000838205-ebird-api-1-1
MIT
Last updated: 2026-03-23
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.
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.
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:
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 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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | summary | |
| confirmLargePayload | No | ||
| maxPaths | No | ||
| pathPrefix | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering safety and idempotency. The description adds valuable context beyond this: 'Side effects: none (read-only local file access)' clarifies the scope, and 'Cost note: full schema is large' warns about payload size. It doesn't contradict annotations but provides practical behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by parameter guidance and behavioral notes in a logical flow. Every sentence adds value: the first states the action, the second covers inputs and defaults, the third explains mode usage, and the fourth adds side effects and cost. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters with no schema descriptions and no output schema, the description does well to explain parameter usage, defaults, and behavioral traits. It covers when to use different modes and warnings about payload size. However, it doesn't detail the response format or error handling, leaving some gaps for a tool with multiple parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates well by explaining parameter purposes: 'mode='summary'' vs. 'full', 'maxPaths=25' for limiting output, 'optional pathPrefix filter' for filtering, and the requirement of 'confirmLargePayload=true' for full mode. It adds meaning beyond the bare schema, though it doesn't detail all constraints like min/max values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('inspect the BirdWeather OpenAPI contract') and resource ('used by this server'), distinguishing it from sibling tools like get_ebird_api and get_system_prompt. It goes beyond the title by specifying it's for reading the API schema, not just a generic 'read' operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use different modes: 'summary is preferred for planning' and 'Set mode='full' with confirmLargePayload=true for full schema.' It also mentions 'optional pathPrefix filter' for specific use cases, offering clear alternatives within the tool itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | summary | |
| confirmLargePayload | No | ||
| maxPaths | No | ||
| pathPrefix | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond annotations: it notes 'side effects: none (read-only local file access)' and 'Cost note: full schema is large; use summary first.' While annotations already indicate readOnlyHint=true and idempotentHint=true, the description provides practical implementation details about payload size and local access.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: it starts with the core purpose, lists required inputs, explains defaults and options, and ends with behavioral notes. Every sentence adds value without redundancy, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 parameters, no output schema), the description is mostly complete: it covers purpose, usage, parameters, and behavioral traits. However, it lacks details on return values (since no output schema exists) and doesn't fully explain all parameter interactions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining parameter semantics: it clarifies that mode has 'summary' and 'full' options, maxPaths defaults to 25, pathPrefix is optional, and confirmLargePayload is required for full mode. However, it doesn't fully explain all parameters (e.g., exact meaning of pathPrefix).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('inspect', 'read') and identifies the resource ('eBird OpenAPI contract used by this server'). It distinguishes from sibling tools like get_birdweather_api by specifying the eBird API schema, not other APIs or system prompts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'use summary first' due to cost concerns, and specifies when to use mode='full' (with confirmLargePayload=true). It implicitly contrasts with siblings by focusing on eBird API inspection, though it doesn't explicitly name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | summary | |
| confirmLargePayload | No | ||
| previewLineCount | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond annotations: it notes 'Side effects: none (read-only local file access)' and 'Cost note: full mode can consume significant tokens.' While annotations cover read-only and idempotent aspects, the description provides practical warnings about token consumption and clarifies the access type, enhancing transparency without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and well-structured: it opens with the usage scenario, lists required inputs and defaults, explains parameter interactions, and adds behavioral notes. Each sentence serves a distinct purpose—no wasted words, and information is front-loaded for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, no output schema), the description is nearly complete: it covers purpose, usage, parameters, and behavioral notes. However, it lacks details on the output format (e.g., what a 'summary' vs. 'full' prompt looks like), leaving a minor gap in contextual understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining all parameters: it states 'Required inputs: none,' lists defaults for mode and previewLineCount, and details the interaction between mode='full' and confirmLargePayload. This adds essential meaning beyond the bare schema, covering semantics and usage conditions effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's purpose: 'when you need operational instructions for BirdStats analysis behavior.' It specifies the verb 'read' (implied from title) and resource 'system prompt,' clearly distinguishing it from sibling tools like get_birdweather_api and get_ebird_api, which likely access different data sources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Use this tool when you need operational instructions for BirdStats analysis behavior.' It also details when to use specific modes (e.g., 'Set mode='full' with confirmLargePayload=true to return full prompt text'), offering clear alternatives within the tool itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.2.0get_birdweather_apiget_ebird_apiget_system_promptEach 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.
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.
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.
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.
Query BigQuery, Snowflake, Redshift & Azure Synapse with natural language
Natural-language queries over a verified emissions knowledge graph, plus standards validation
Your Plaud recordings in natural language: list recordings, read speaker-attributed transcripts and
Your Databricks Lakehouse in natural language: run SQL on your SQL warehouses, track long-running qu
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/DMontgomery40/mcp-server-birdstats'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
