convez.ai
MCP ServerIntegração & APIsIntermediário
daraobeirnecode

Esri MCP – Acesso a ArcGIS para Agentes IA

daraobeirnecode/esri-mcp

Integre ArcGIS (AGOL + Enterprise) com agentes Claude via MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que expõe dados e serviços do ArcGIS Online e ArcGIS Enterprise como ferramentas para agentes LLM. Permite consultas espaciais, geocodificação, listagem de camadas e busca em portais, com normalização inteligente de respostas e proteção de contexto.

Instalação

$npx convez-ai daraobeirnecode/esri-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Consultas geoespaciais e análise de dados cartográficos
  • Geocodificação e reverse geocoding em aplicações de IA
  • Busca e descoberta de dados em portais ArcGIS
  • Automação de fluxos que combinam mapas com raciocínio de LLM

Veredito

Solução bem arquitetada para conectar ecossistema Esri com agentes Claude. Prioriza robustez (tratamento de erros, proteção de contexto, normalização) sobre cobertura ampla, deixando operações de escrita fora do escopo. Recomendado para equipes que trabalham com SIG e precisam de integração sem dependências pesadas.

README

A tradução para o português deste README ainda está na fila.

esri-mcp

An MCP server that exposes ArcGIS data and services — both ArcGIS Online and ArcGIS Enterprise — as tools for LLM agents.

Point an agent at any ArcGIS REST endpoint and it can discover layers, inspect schemas, run attribute and spatial queries, geocode addresses, and search portal content. Built on raw ArcGIS REST via httpx (no 500 MB arcgis package dependency), with FastMCP over stdio.

Read-only by design. Write operations (applyEdits, delete, publish) are out of scope for v1.

Tools

ToolWhat it does
list_layersList all layers and tables on a MapServer/FeatureServer
get_layer_infoLayer metadata: real field names (not aliases), geometry type, record limits
query_featuresSQL where + optional spatial filter; paginated, date-normalized, geometry off by default
geocode_addressAddress/place → lon/lat candidates (AGOL World Geocoder)
reverse_geocodeLon/lat → nearest street address
search_portal_itemsKeyword search across ArcGIS Online or an Enterprise portal
get_item_detailsFull details for one portal item by id

Designed for LLM consumption

Raw Esri JSON is verbose, inconsistent, and full of traps. This server normalizes at the boundary:

  • Esri errors actually raise. Esri returns HTTP 200 with an error body; every response is checked and surfaced as a clean message ("Layer 9 not found on service X — service has layers: 0, 1, 2"), never an HTML page or raw traceback.
  • Context-window protection. Queries default to returnGeometry=false and outSR=4326, paginate through exceededTransferLimit, cap at 5,000 records, and report count / truncated / source_url so the agent can cite and paginate. Requested geometry is simplified via maxAllowableOffset.
  • Dates are ISO 8601 strings, not epoch milliseconds.
  • Real field names. get_layer_info returns the queryable field name alongside its display alias — where clauses fail silently against aliases.
  • Long requests go as POST automatically (IIS URL-length limits on Enterprise servers).
  • Geocoding stays transactional (forStorage=false) to remain within free-tier terms.

Quick start

Requires uv (Python 3.12+ is fetched automatically).

git clone https://github.com/<you>/esri-mcp.git
cd esri-mcp
uv sync
uv run python -m esri_mcp     # starts the server on stdio

Register with Claude Code

claude mcp add esri -- uv run --directory /path/to/esri-mcp python -m esri_mcp

Debug interactively

npx @modelcontextprotocol/inspector uv run python -m esri_mcp

Try it

No credentials needed for public services. Ask your agent something like:

List the layers on https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer, then show me the five most populous states.

Authentication

Anonymous access works out of the box — most public services need no token. For secured content, set env vars for one of three modes (checked in this order; see .env.example):

ModeEnv varsUse for
API keyARCGIS_API_KEYArcGIS Online API keys
OAuth2ARCGIS_CLIENT_ID, ARCGIS_CLIENT_SECRETAGOL app registration (client_credentials)
Legacy tokenARCGIS_USERNAME, ARCGIS_PASSWORD, ARCGIS_PORTAL_URLOn-prem ArcGIS Enterprise (generateToken)

Tokens are cached in-process and refreshed 5 minutes before expiry. If a stale token hits a public endpoint, the request falls back to anonymous instead of failing. Setting ARCGIS_PORTAL_URL also points search_portal_items / get_item_details at your Enterprise portal instead of arcgis.com.

Credentials never appear in logs, error messages, or tool output.

Development

uv sync                                   # install deps (incl. dev group)
uv run pytest -q -m "not integration"     # offline unit tests (mock transport + recorded JSON)
uv run pytest -q -m integration           # live tests against sampleserver6.arcgisonline.com
uv run pytest -q                          # everything
uv run ruff check . && uv run ruff format --check .   # lint + format check

Every Esri REST gotcha has a regression test: error-in-200 bodies, HTML-instead-of-JSON responses, pagination stitching, truncation flagging, epoch-date conversion, alias-vs-field-name, POST-for-long-queries, and anonymous fallback.

Layout

esri_mcp/
  server.py          # FastMCP app, tool registration, transport (stdio; one-line swap to HTTP)
  auth.py            # token acquisition + caching (API key / OAuth2 / generateToken / anonymous)
  client.py          # httpx wrapper: retries, f=json, error normalization, POST fallback
  models.py          # Pydantic request/response models
  tools/
    layers.py        # discovery + metadata
    query.py         # feature queries: pagination, date conversion, record caps
    geocode.py       # geocode / reverse geocode (AGOL World Geocoder)
    portal.py        # item search, item details
tests/               # unit tests (offline) + live integration tests (marked)

Roadmap

  • streamable-http transport for hosted use (n8n, Hermes) — already a one-line swap in server.py
  • Write operations behind an explicit ESRI_MCP_ALLOW_WRITES=true gate

License

MIT

Ver o original no GitHub

Bom para

Relacionados