MCP EcoTaxa

A standalone local MCP server for querying a read-only EcoTaxa cache from any MCP-compatible agent.

Each person runs their own container and local cache. No NeoLab server, IDEA instance, or shared cache is required.

For a plain-language overview of what an agent can do with this MCP, read CAPABILITIES.md.

Quick Start

Requirements: Docker Desktop and an MCP-compatible agent such as Codex, Claude Code, or Copilot. A validated cache snapshot is downloaded from this repository's GitHub release. You do not need an EcoTaxa account to explore it.

1. Clone

git clone https://github.com/TidianeCisse777/mcp-ecotaxa.git
cd mcp-ecotaxa
cp .env.example .env

Do not change .env for a first exploration: consumer mode and the default cache release are already configured.

Optional capabilities require adding a private value to your local .env; they are not needed to explore the released cache:

• EcoPart enrichment: ECOPART_TOKEN, or ECOTAXA_USERNAME and ECOTAXA_PASSWORD.
• Access to a private cache release: ECOTAXA_CACHE_RELEASE_TOKEN.

Use Your Own EcoTaxa Cache

Instead of the shared released snapshot, you can build a personal local cache from the EcoTaxa projects your account can access. Add the following to your private .env:

ECOTAXA_CACHE_MODE=publisher
ECOTAXA_TOKEN=your-ecotaxa-token
ECOTAXA_CACHE_AUTO_PUBLISH=false

Publisher mode uses a Docker volume separate from the released consumer cache. It is refreshed from EcoTaxa and is never uploaded to this repository. Use ECOTAXA_USERNAME and ECOTAXA_PASSWORD instead of ECOTAXA_TOKEN only when token authentication is unavailable.

2. Start

docker compose up --build -d
curl http://localhost:8001/health

On its first start, the container downloads and verifies the SQLite snapshot. It is ready when the response contains samples_indexed > 0, projects_indexed > 0, and last_sync_status: "ok".

3. Get the Token

When MCP_AUTH_TOKEN is empty (the default), the container creates a durable token on its first start. Retrieve it once:

docker compose exec ecotaxa-mcp cat /app/cache/.mcp_auth_token

Keep it private: your agent uses this secret to connect to the MCP server.

4. Connect Your Agent

Choose the relevant section below. Every configuration uses the same local URL and the token from step 3.

To follow startup in detail, use a second terminal:

docker compose logs -f ecotaxa-mcp

Connecting an Agent

The container listens locally at http://localhost:8001/mcp using Streamable HTTP. MCP configuration is a one-time manual step for each agent host.

Codex

Define the secret in the environment that starts Codex:

export ECOTAXA_MCP_TOKEN='the-value-from-MCP_AUTH_TOKEN'

Add this to ~/.codex/config.toml:

[mcp_servers.ecotaxa]
url = "http://localhost:8001/mcp"
bearer_token_env_var = "ECOTAXA_MCP_TOKEN"

Restart Codex. The ecotaxa server and its tools then appear in the session.

Claude Code

export ECOTAXA_MCP_TOKEN='the-value-from-MCP_AUTH_TOKEN'
claude mcp add --transport http \
  --header "Authorization: Bearer $ECOTAXA_MCP_TOKEN" \
  ecotaxa http://localhost:8001/mcp

The command registers the server in Claude Code. In a chat, ask: “Use MCP EcoTaxa to …”.

GitHub Copilot CLI

export ECOTAXA_MCP_TOKEN='the-value-from-MCP_AUTH_TOKEN'
copilot mcp add --transport http \
  --header "Authorization: Bearer $ECOTAXA_MCP_TOKEN" \
  ecotaxa http://localhost:8001/mcp

The server is registered in ~/.copilot/mcp-config.json. Then ask Copilot CLI: “Use MCP EcoTaxa to explore the available samples …”.

GitHub Copilot Chat in VS Code

In VS Code, use MCP: Open User Configuration or create .vscode/mcp.json in your project:

{
  "servers": {
    "ecotaxa": {
      "type": "http",
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer ${input:ecotaxa-mcp-token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "ecotaxa-mcp-token",
      "description": "MCP EcoTaxa token",
      "password": true
    }
  ]
}

VS Code asks for the token at first startup and stores it securely.

Copilot Cloud Agent on GitHub.com

The locally cloned server cannot be used by a Copilot cloud agent: localhost refers to its GitHub environment, not your computer. Deploy the MCP behind an HTTPS URL reachable from the cloud. Then, in Settings → Copilot → MCP servers for the repository, declare that HTTP server and an agent secret named COPILOT_MCP_ECOTAXA_TOKEN:

{
  "mcpServers": {
    "ecotaxa": {
      "type": "http",
      "url": "https://your-mcp.example/mcp",
      "headers": {
        "Authorization": "Bearer $COPILOT_MCP_ECOTAXA_TOKEN"
      },
      "tools": ["*"]
    }
  }
}

Copilot cloud agents use MCP tools but not MCP prompts. Add the EcoTaxa navigation rules to the agent instructions as well.

Other MCP Clients

For Cursor or another client that accepts an HTTP MCP declaration, add the equivalent configuration below, replacing the token:

{
  "mcpServers": {
    "ecotaxa": {
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_AUTH_TOKEN"
      }
    }
  }
}

If your agent runs in another Docker container, localhost refers to that container rather than the MCP. Put both containers on the same Docker network and use http://ecotaxa-mcp:8001/mcp, or use host.docker.internal:8001 when the runtime supports it.

What the Server Provides

The server is strictly read-only. It does not modify EcoTaxa, write to projects, or download a complete EcoTaxa object archive. Its local cache supports filtering, joining, counting, grouping, and ranking samples.

The available tools are:

• list_tables and describe_table to inspect the schema when needed;
• read_query for read-only SQL exploration;
• cache_status to inspect cache freshness;
• export_query_tsv to return a selected result as TSV;
• enrich_ecopart for an EcoTaxa object TSV joined with EcoPart;
• enrich_amundsen_ctd for CTD variables linked by CTD filename.

The ecotaxa_navigation MCP prompt gives supporting agents detailed rules about data grain, taxonomy, ambiguity, objects, and persistence. The main tools also contain the most important guidance for clients that do not load MCP prompts automatically.

One row in samples_cache represents one EcoTaxa sample. project_id is its parent project, profile_id is a profile/cast, and station_id is a station. Missing dates, depths, and coordinates are unknown and must not be treated as negative values. IHO physical zones and MEOW ecoregions must remain separate.

read_query accepts one read-only SELECT or CTE and returns at most 500 rows. Use LIMIT and OFFSET to page larger requests.

TSV Results

After a useful query, the agent should offer TSV conversion only when you want to keep, download, share, or reuse the selection. export_query_tsv returns {filename, tsv} to the host agent. The host agent saves the content in its own workspace; the MCP server does not create or keep a file.

External Enrichments

Every enrichment begins with a plan without a network request. The agent shows that plan and proceeds with confirmed=true only after you agree.

EcoPart

enrich_ecopart accepts the contents of an already exported EcoTaxa object TSV, never cache SQL or a sample TSV. It requires an object ID, project_id, a profile/sample identifier, and object depth. It retrieves the linked EcoPart profiles, joins each object by profile and 5 m depth bin, and returns ecotaxa_ecopart_enriched.tsv to the host agent. It requires EcoPart access: add ECOPART_TOKEN, or ECOTAXA_USERNAME and ECOTAXA_PASSWORD, to .env.

Amundsen CTD

enrich_amundsen_ctd requires ctd_rosette_filename. The filename identifies the profile in Amundsen ERDDAP; station, time, and position make the match auditable, and the measurement at the nearest source depth in PRES is used. No account is required.

The MCP keeps no external-enrichment result in its cache or container. Amundsen returns structured rows; EcoPart returns an enriched TSV and a preview. The host agent keeps the result in its DataFrame, session, or a file only when you ask it to.

Updating the Cache (Maintainers Only)

To create a new cache release, set ECOTAXA_CACHE_MODE=publisher, provide EcoTaxa credentials, and provide a GITHUB_TOKEN with write access to this repository. After a complete successful synchronization, the server replaces the assets of the ecotaxa-cache-current release.

Add these private values to the maintainer's .env:

ECOTAXA_CACHE_MODE=publisher
ECOTAXA_TOKEN=your-ecotaxa-token
GITHUB_TOKEN=your-github-token

Use ECOTAXA_USERNAME and ECOTAXA_PASSWORD instead of ECOTAXA_TOKEN only when token authentication is unavailable. Advanced synchronization settings remain optional: ECOTAXA_NIGHTLY_SYNC, ECOTAXA_SYNC_HOUR, ECOTAXA_CACHE_MAX_AGE_HOURS, and ECOTAXA_CACHE_AUTO_PUBLISH.

Quick Check

curl http://localhost:8001/health

A 200 response confirms the server is reachable. When the cache is ready, ask, for example: “List samples in Baffin Bay” or “Which UVP6 projects are available?”.

Development

python -m pip install -r requirements-dev.txt
pytest -q tests/test_mcp_tool_surface.py tests/test_mcp_health.py tests/test_mcp_scheduler.py

EcoTaxa credentials and MCP tokens must remain exclusively in .env.