mireye-mcp

Developed in a private monorepo. This repository (Mireye-Labs/mireye-earth-mcp) is the published source of the mireye-mcp PyPI package, snapshot-synced on every release. Issues and PRs are welcome here (changes are applied upstream and re-synced; the test suite runs in the monorepo); releases land via PyPI.

Expose Mireye Earth's /v1/ask and /v1/fetch endpoints to MCP clients that need a local stdio adapter (Claude Desktop, Cursor, custom agents built on the mcp Python SDK) as native tools — no HTTP wiring required.

This is a standalone PyPI package (mireye-mcp) with only two runtime dependencies — httpx and mcp. It does not pull in the geospatial backend, so there's no GDAL / rasterio / DuckDB build step.

The server is a local stdio adapter with no geospatial business logic: tool handlers POST to the deployed Mireye HTTP API, while read-only MCP resources fetch and cache the public field catalog.

Mireye also exposes a hosted remote MCP endpoint at https://api.mireye.com/mcp for clients that support Streamable HTTP and native OAuth. Use that hosted endpoint for Claude Code so /mcp opens the browser sign-in flow. This package remains the local stdio path; it uses mireye-mcp login or MIREYE_BEARER_TOKEN for credentials.

What the agent gets

Six tools, all prefixed mireye_ so they sort together and don't collide with generic ask / fetch tools from other MCP servers:

Catalog context is exposed as MCP resources instead of extra tools:

Workflow prompts are also registered — 22 in total. Claude Code surfaces MCP prompts as slash commands under the form /mcp__<server>__<prompt>.

There is no third list_fields tool. Agents that need the catalog should read the MCP resources above; the stdio adapter backs them with GET /v1/meta/fields and a 1-hour ETag-aware cache.

Install local stdio — one command with uvx

uvx mireye-mcp

That's it. uvx (bundled with uv) downloads the package into a managed cache, runs the entry point, and the next invocation is instant. No venv to manage, no pip install, no native builds.

If you don't have uv:

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

Plain pip also works:

pip install mireye-mcp
mireye-mcp  # entry point

Official MCP Registry

This server is published to the Official MCP Registry as com.mireye/earth — the entry is live (the publish job ships from release.yml), and mireye-mcp 0.2.0 is on PyPI. The registry entry carries both distributions:

• the PyPI package mireye-mcp (local stdio, run via uvx), and
• the hosted remote https://api.mireye.com/mcp (Streamable HTTP + OAuth) for clients that prefer a remote server.

Because the entry is live, registry-aware clients (VS Code, the GitHub MCP Registry, and anything else that reads the official registry) can discover and install it from there — no manual config required.

Wire it into Claude Desktop

First authenticate the local adapter:

mireye-mcp login

For non-interactive hosts, set MIREYE_BEARER_TOKEN instead.

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Restart Claude Desktop. The six tools (mireye_ask, mireye_fetch, mireye_geocode, mireye_lookup, mireye_request_field, mireye_field_request_status) appear under the 🔌 menu, with catalog resources and prompts available to clients that surface those MCP primitives.

To point at a self-hosted deployment instead of the default Fly URL:

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

Wire it into Claude Code

Use the hosted HTTP MCP endpoint instead of this local stdio package:

claude mcp remove mireye-earth -s user   # only needed if an old stdio entry exists
claude mcp add --transport http --scope user mireye-earth https://api.mireye.com/mcp

Restart Claude Code, run /mcp, and follow the browser OAuth flow. Slash commands appear as:

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

Or just chat naturally — Claude Code will call the tool when relevant.

Wire it into Cursor

Cursor's MCP config lives at ~/.cursor/mcp.json (global) or <repo>/.cursor/mcp.json (workspace). Same shape as Claude Desktop:

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

Open Cursor → Settings → MCP and confirm mireye-earth shows the two green tools. Catalog resources and prompts appear when the client supports those MCP primitives.

Wire it into a custom agent

If you're building an MCP client with the mcp Python SDK, point its StdioServerParameters at the installed entry point:

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

params = StdioServerParameters(command="uvx", args=["mireye-mcp"])

async with stdio_client(params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()
        # tools.tools is [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": "elevation?"},
        )

Configuration