Esri MCP – Acesso a ArcGIS para Agentes IA
daraobeirnecode/esri-mcp
Integre ArcGIS (AGOL + Enterprise) com agentes Claude via MCP
Ver no GitHubServidor 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-mcp1 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
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
| Tool | What it does |
|---|---|
list_layers | List all layers and tables on a MapServer/FeatureServer |
get_layer_info | Layer metadata: real field names (not aliases), geometry type, record limits |
query_features | SQL where + optional spatial filter; paginated, date-normalized, geometry off by default |
geocode_address | Address/place → lon/lat candidates (AGOL World Geocoder) |
reverse_geocode | Lon/lat → nearest street address |
search_portal_items | Keyword search across ArcGIS Online or an Enterprise portal |
get_item_details | Full 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
errorbody; 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=falseandoutSR=4326, paginate throughexceededTransferLimit, cap at 5,000 records, and reportcount/truncated/source_urlso the agent can cite and paginate. Requested geometry is simplified viamaxAllowableOffset. - Dates are ISO 8601 strings, not epoch milliseconds.
- Real field names.
get_layer_inforeturns the queryable field name alongside its display alias —whereclauses 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):
| Mode | Env vars | Use for |
|---|---|---|
| API key | ARCGIS_API_KEY | ArcGIS Online API keys |
| OAuth2 | ARCGIS_CLIENT_ID, ARCGIS_CLIENT_SECRET | AGOL app registration (client_credentials) |
| Legacy token | ARCGIS_USERNAME, ARCGIS_PASSWORD, ARCGIS_PORTAL_URL | On-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-httptransport for hosted use (n8n, Hermes) — already a one-line swap inserver.py- Write operations behind an explicit
ESRI_MCP_ALLOW_WRITES=truegate
License
MIT