Install edi-mcp¶

edi-mcp is a Python 3.11+ package with one command, edi-mcp, that MCP clients start over stdio. These instructions cover macOS, Linux and Windows.

Prerequisites¶

• uv¹, which installs Python 3.11+ for edi-mcp if your system lacks it, and keeps the server in its own environment.
• git, for the install script and installs from source.
• Optional: an EDI API key. Without one, edi-mcp answers from the anonymous DataONE replicas of EDI content.

Install uv²:

curl -LsSf https://astral.sh/uv/install.sh | sh
# or: brew install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# or: winget install --id=astral-sh.uv -e

Open a new terminal afterwards so uv is on your PATH.

Option 1: From source with the install script (recommended)¶

git clone https://github.com/idss-mesa/edi-mcp.git
cd edi-mcp
scripts/install.sh

scripts/install.sh creates the server environment (uv sync) if .venv/bin/edi-mcp is missing, then registers that executable with every supported agent it finds on your machine: Claude Code, Claude Desktop, OpenAI Codex CLI, Gemini CLI, Goose and OpenCode. It prefers each agent's own CLI when one is installed (claude mcp add, codex mcp add, gemini mcp add) and otherwise merges an entry into the agent's config file, keeping everything else in the file and leaving a .bak copy.

scripts/install.sh --with-key                    # also store your EDI API key (see below)
scripts/install.sh --agents all --dry-run        # preview the change for every agent
scripts/install.sh --agents claude,goose         # just Claude Code and Goose
scripts/install.sh --scope project               # project-level config (claude, codex, gemini, opencode)
scripts/install.sh --env EDI_MCP_SERVER__LOG_LEVEL=debug   # any extra environment variable
scripts/install.sh --command "$(command -v edi-mcp)"       # register a uv-tool install instead
scripts/install.sh --uninstall                   # remove the registration everywhere

The script writes the absolute path of the executable, because desktop apps do not inherit your shell PATH. It needs bash; macOS's built-in bash 3.2 is enough. Restart desktop apps (Claude Desktop, Goose Desktop) after installing.

The EDI API key and the script¶

There is deliberately no option that takes the key itself, since command lines end up in shell history and process lists. --with-key reads EDI_API_KEY from your environment, or asks for it with hidden input, and writes it into each agent's server env:

read -rs EDI_API_KEY && export EDI_API_KEY     # paste the key, press Enter
scripts/install.sh --with-key

• The key is then stored in plain text in each agent's config file. The script restricts the files it writes, and their .bak copies, to your user (mode 600), and masks the key as *** in everything it prints, including the output of the agent CLIs it calls.
• For agents registered through their own CLI (Claude Code, Codex, Gemini CLI), the key is passed to that CLI's mcp add command and is briefly visible in the process list. Add --prefer-files to have Codex and Gemini CLI configured by file instead.
• Without --with-key no key is stored, and the server uses the anonymous DataONE backend unless the agent passes EDI_API_KEY to it some other way.

Windows¶

On Windows, register by hand (Option 2) or run the script from Git Bash, which converts paths to Windows form and writes Claude Desktop's config under %APPDATA%. Git Bash support has not been tested as widely as macOS and Linux; check the result with --dry-run first. Do not run the script inside WSL to configure Windows apps: it would write WSL's own config files, which Claude Desktop for Windows never reads.

Option 2: Install the package and register it by hand¶

Install the edi-mcp command:

uv tool install git+https://github.com/idss-mesa/edi-mcp

uvx --from git+https://github.com/idss-mesa/edi-mcp edi-mcp --version

pipx install git+https://github.com/idss-mesa/edi-mcp
# or, inside a virtual environment:
pip install "git+https://github.com/idss-mesa/edi-mcp"

git clone https://github.com/idss-mesa/edi-mcp
cd edi-mcp
uv sync                      # creates .venv with the package
uv run edi-mcp --version

Then find the executable's absolute path, which is what desktop apps need:

command -v edi-mcp           # e.g. /Users/you/.local/bin/edi-mcp
# from source: /path/to/edi-mcp/.venv/bin/edi-mcp

(Get-Command edi-mcp).Source  # e.g. C:\Users\you\.local\bin\edi-mcp.exe
# from source: C:\path\to\edi-mcp\.venv\Scripts\edi-mcp.exe

and register it with your client. The shortest form, for Claude Code:

claude mcp add edi -s user -e EDI_API_KEY="$EDI_API_KEY" -- edi-mcp

Claude Desktop, and other JSON-configured clients:

{
  "mcpServers": {
    "edi": {
      "command": "/ABSOLUTE/PATH/TO/edi-mcp",
      "args": [],
      "env": { "EDI_API_KEY": "paste-your-key-here" }
    }
  }
}

Use absolute paths (not ~/ or ./). On Windows escape backslashes: "C:\\Users\\You\\.local\\bin\\edi-mcp.exe". Leave out env to run without a key. Clients has the entries for Claude Desktop, Codex CLI, Gemini CLI, Goose, OpenCode, VS Code and hosted servers.

Option 3: Docker¶

A container image (python:3.13-slim, non-root, HTTP on port 8080 with a /healthz check) is planned for the v0.1.0 release; see the Roadmap. There is no Dockerfile yet.

Verify the installation¶

edi-mcp --version     # edi-mcp 0.1.0
edi-mcp --check       # {"ok": true, "version": "0.1.0", "protocolVersion": "2026-07-28", "transport": "stdio", "keyConfigured": false, "backend": "dataone"}

--check loads your configuration, calls edi_ping in-process and prints a one-line JSON report: the version, protocol, transport, whether an EDI API key is configured and which backend that selects (pasta with a key, dataone without). It makes no network request, so it does not prove that EDI accepts your key. For that, ask your agent to call edi_ping with check_api=true once the server is connected; see EDI API key. --print-config shows the effective settings with the key replaced by ***.

In Claude Code, claude mcp list runs a health check and shows edi as connected. To talk to the server directly over stdio:

# 2026-07-28 client: every request carries the protocol envelope in _meta
echo '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{},"io.modelcontextprotocol/clientInfo":{"name":"manual","version":"0"}}}}' \
  | edi-mcp

# 2025-era client: classic initialize handshake, then tools/list
printf '%s\n%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"manual","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | edi-mcp

Both print JSON-RPC responses on stdout (logs go to stderr) and exit once stdin closes. server/discover reports the server's capabilities and instructions; a tools/list request with the same _meta envelope lists every tool (see the Tool reference).

Configuration¶

Nothing is required. The settings most people touch:

EDI_API_KEY=                      # optional; PASTA with it, DataONE without
EDI_MCP_SERVER__LOG_LEVEL=info    # debug | info | warning | error | critical (stderr)
EDI_MCP_DOWNLOADS__DIRECTORY=     # where the planned download tools may write

edi-mcp does not read .env files on its own. See Configuration for every setting, the YAML file and the precedence rules.

Troubleshooting¶

edi-mcp: command not found from a desktop app. Desktop apps do not read your shell profile. Use the executable's absolute path as the command; the install script does this for you.

Server shows as disconnected. Run the configured command yourself with --check. If it fails, re-create the environment (uv sync in a clone, or uv tool install --reinstall git+https://github.com/idss-mesa/edi-mcp). Claude Desktop logs live in ~/Library/Logs/Claude/ (macOS) or %APPDATA%\Claude\logs\ (Windows); in Claude Code, claude mcp get edi shows the connection status.

backend is dataone although you have a key. The key did not reach the server process: desktop apps do not see variables exported in your shell. Put it in the client's env block, or re-run the install script with --with-key.

upstream_forbidden errors. EDI refused the key; without a reason it is mistyped, expired or deleted. With reason: access_restricted the key works but the package is restricted. See EDI API key.

Port already in use. MCP over stdio uses no network port; a port error comes from an HTTP deployment (--transport http, port 8080 by default) or something else on your machine.

Windows paths. In JSON, write backslashes doubled (C:\\Users\\…) or use forward slashes. Point at edi-mcp.exe, not the extension-less name.

Upgrading¶

# install script / from source
git pull origin main && uv sync
# uv tool
uv tool upgrade edi-mcp

Registrations made by the install script keep pointing at .venv/bin/edi-mcp, so git pull && uv sync is enough; restart desktop apps afterwards.

Uninstallation¶

--uninstall leaves each edited file's .bak copy behind; if you used --with-key, those backups (owner-only, like the files) still contain the key, so delete them too.

scripts/install.sh --uninstall   # remove the server from every agent config
cd .. && rm -rf edi-mcp          # if installed from source
uv tool uninstall edi-mcp        # if installed with uv tool

Next steps¶

• Quickstart: a first session.
• EDI API key: create a key and give it to edi-mcp.
• Clients: per-client configuration.
• Configuration: every setting.