Install - Mireye Earth

Mireye serves a hosted OAuth-protected MCP endpoint at https://api.mireye.com/mcp. Use this remote HTTP endpoint for Claude Code so /mcp can open the browser sign-in flow and Claude Code can store and refresh OAuth credentials for you. Mireye also ships a local stdio adapter (mireye-mcp) for Claude Desktop, Cursor, and custom agents that do not use hosted HTTP MCP. Local stdio does not launch Claude’s native OAuth flow; it requires mireye-mcp login or MIREYE_BEARER_TOKEN. Both distributions ship under the MCP server name com.mireye/earth. Publication to the Official MCP Registry is in flight — until the entry is live, use the manual setup below (it is the same config either way).

Claude Code — hosted OAuth

If you previously configured the local stdio adapter under the same name, remove it first:

claude mcp remove mireye-earth -s user

Then add the hosted MCP endpoint:

claude mcp add --transport http --scope user mireye-earth https://api.mireye.com/mcp

Restart any running Claude Code session, then run /mcp and follow the browser login flow. After authentication, both tools (mireye_ask, mireye_fetch) are available for natural chat and tool calls. Catalog resources and workflow prompts are also available to clients that surface those MCP primitives. Matching slash commands also appear:

/mcp__mireye-earth__mireye_ask <lat> <lng> <question>
/mcp__mireye-earth__mireye_fetch <lat> <lng> [fields] [preset]

(The /mcp__<server>__<prompt> format is Claude Code’s slash-command convention for MCP prompts — it isn’t customizable.)

Local stdio adapter — fallback

Use the local adapter when your MCP client does not support remote HTTP OAuth, or when you need a local stdio process. It exposes the same two tools, catalog resources, and prompts, and ships as its own slim PyPI package: two runtime dependencies (httpx + mcp), no native builds, no GDAL. Install with uvx:

uvx mireye-mcp

The six siting presets (catalog 0.6.0) and the credential URL-binding behavior described on this page require mireye-mcp >= 0.2.0. If pip index versions mireye-mcp returns nothing yet, the release is in flight — use the hosted endpoint until it lands.

uvx (bundled with uv) downloads the package on first run, caches it, and the next invocation is instant. No venv to manage. Don’t have uv?

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

Plain pip works too:

pip install 'mireye-mcp>=0.2.0'

This installs the mireye-mcp console entry point. Verify:

which mireye-mcp
# /Users/you/.local/bin/mireye-mcp  (or similar)

Claude Desktop

Edit the Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add mireye-earth to mcpServers:

{
  "mcpServers": {
    "mireye-earth": {
      "command": "uvx",
      "args": ["mireye-mcp"]
    }
  }
}

After running mireye-mcp login or setting MIREYE_BEARER_TOKEN, restart Claude Desktop. Two tools — mireye_ask and mireye_fetch — appear in the 🔌 menu, with catalog resources and workflow prompts available to clients that expose them. Click through to confirm both tools are green; then start a new chat and ask:

What’s the elevation at 40.7128, -74.0060?

Claude calls mireye_ask, returns the cited answer.

`uvx` not on PATH?

macOS launches GUI apps with a minimal PATH (no shell profile loaded). If your uv install lives at ~/.local/bin/uvx, that path may not be visible to Claude. Use the absolute path:

{
  "mcpServers": {
    "mireye-earth": {
      "command": "/Users/you/.local/bin/uvx",
      "args": ["mireye-mcp"]
    }
  }
}

which uvx from a terminal gives you the absolute path.

Cursor

Cursor reads MCP config from one of:

~/.cursor/mcp.json (global)
<repo>/.cursor/mcp.json (workspace)

Same shape as Claude Desktop:

{
  "mcpServers": {
    "mireye-earth": {
      "command": "uvx",
      "args": ["mireye-mcp"]
    }
  }
}

Open Cursor → Settings → MCP. The mireye-earth server should show two tools with green status indicators. Resource and prompt visibility depends on the Cursor MCP UI version.

Custom MCP agent (Python SDK)

If you’re embedding MCP in your own agent loop, use the official mcp Python SDK to talk to the server:

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

PARAMS = StdioServerParameters(
    command="uvx",
    args=["mireye-mcp"],
    # Optional: env vars passed to the spawned process.
    env={"MIREYE_BASE_URL": "https://api.mireye.com"},
)

async def main():
    async with stdio_client(PARAMS) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            tools = await session.list_tools()
            print([t.name for t in tools.tools])
            # ['mireye_ask', 'mireye_fetch']
            resources = await session.list_resources()
            prompts = await session.list_prompts()

            result = await session.call_tool(
                "mireye_ask",
                {
                    "lat": 40.7128,
                    "lng": -74.0060,
                    "question": "What is the elevation here?",
                },
            )
            print(result.content)

asyncio.run(main())

The result.content is the verbatim JSON body from POST /v1/ask. See the tool reference for the input schemas.

Configuration

Both tools share the same configuration, set via environment variables on the MCP server process:

Env var	Default	Purpose
`MIREYE_BASE_URL`	`https://api.mireye.com`	HTTP base URL the tools POST to. Useful for staging / self-hosted deploys. Stored login credentials only attach when they were created against this same URL.
`MIREYE_TIMEOUT_S`	`120`	Per-request timeout (seconds). Must exceed the ~110 s `/v1/ask` server deadline; the default already covers cold starts. Raise it further (never below 120) only if you still time out.
`MIREYE_BEARER_TOKEN`	unset	Optional Mireye bearer token. Overrides stored credentials for tool calls; `status` reports on the stored login first.
`MIREYE_MCP_CREDENTIALS_FILE`	`~/.config/mireye-mcp/credentials.json`	Stored credential file used by login/status/logout.

Set them in the agent’s MCP config:

{
  "mcpServers": {
    "mireye-earth": {
      "command": "uvx",
      "args": ["mireye-mcp"],
      "env": {
        "MIREYE_BASE_URL": "https://staging.mireye.example"
      }
    }
  }
}

Verify with MCP Inspector

The MCP Inspector is the canonical way to debug a server end-to-end:

npx @modelcontextprotocol/inspector uvx mireye-mcp

It opens a web UI showing the server’s tools, resources, and prompts, lets you call each one with synthetic arguments, and tails stderr logs from the server process. A passing smoke check:

Tools list shows exactly two entries: mireye_ask, mireye_fetch.
Resources list shows mireye://catalog/fields, mireye://catalog/presets, and mireye://catalog/us-envelope.
Prompt list includes mireye_site_report, mireye_flood_check, mireye_wildfire_underwrite, and mireye_pick_fields.
Call mireye_ask with lat: 40.7128, lng: -74.006, question: "elevation?" — get a JSON response with answer, confidence, citations.
Call mireye_fetch with lat: 40.7128, lng: -74.006, fields: ["elevation"] — get a JSON response with fields.elevation.value populated.

Authentication

The local stdio adapter does not launch native MCP OAuth. It runs on your machine and uses a one-time device login to store a Mireye API token locally. Run:

mireye-mcp login

The command prints a verification URL and code, waits while you approve the code in the Mireye account page, and stores a local API token. You can check or clear credentials with:

mireye-mcp status
mireye-mcp logout
mireye-mcp logout --revoke

Stored credentials are bound to the MIREYE_BASE_URL that login ran against, and the token is only ever sent to that same URL. If you later point MIREYE_BASE_URL somewhere else (staging, self-hosted), tool calls behave as logged out and the error names both URLs — re-run mireye-mcp login against the new URL, or set MIREYE_BEARER_TOKEN explicitly. Tokens are also never sent over plain http://, except to loopback hosts (localhost / 127.0.0.1 / [::1]) for local development. status and logout --revoke use the stored URL, so you can always inspect or revoke a stored login. For non-interactive hosts, set MIREYE_BEARER_TOKEN in the MCP config. The MCP server only forwards bearer tokens; Firebase verification and account policy live in the HTTP API. Remote MCP clients should connect to https://api.mireye.com/mcp instead. They will receive the OAuth metadata and complete a browser OAuth 2.1 + PKCE flow automatically when the client supports remote MCP authorization.

Updating

Switching from the old mireye-earth-mcp package? Credentials now live in ~/.config/mireye-mcp/credentials.json (the old path was ~/.config/mireye-earth-mcp/), so the first run after switching looks unauthenticated. Re-run mireye-mcp login once to re-authenticate.

With uvx, just re-invoke — uvx checks for a new version on each cold call (or pin explicitly with uvx mireye-mcp@latest):

uvx mireye-mcp@latest

With pip:

pip install --upgrade mireye-mcp

Then restart Claude Desktop / Cursor so the new server binary is picked up. Tool input schemas are stable within a minor version; check the catalog page for any field additions.

​Claude Code — hosted OAuth

​Local stdio adapter — fallback

​Claude Desktop

​uvx not on PATH?

​Cursor

​Custom MCP agent (Python SDK)

​Configuration

​Verify with MCP Inspector

​Authentication

​Updating