arcgis-portal-mcp

v1.8.0. 60 tools for ArcGIS Enterprise Portal and ArcGIS Online.

A Model Context Protocol (MCP) server that gives AI assistants direct access to your ArcGIS content. Search, inspect, edit, publish, and admin through natural language.

Works with Claude Desktop, Cursor, VS Code Copilot, and any MCP-compatible client.

Disclaimer: This is an independent open-source project. Not affiliated with, endorsed by, or sponsored by Esri. "ArcGIS" is a registered trademark of Esri.

What's new in v1.8.0

• Collaborations: list, inspect, and trigger sync for distributed GIS collaborations
• Roles & privileges: list organization roles with their full privilege sets
• Scheduled tasks: list and filter organization-wide or per-user scheduled tasks

What's new in v1.7.0

• Webhooks: list, create, update, delete, and test organization webhooks for portal automation
• Logs: query and clean portal logs with level/source/time filters
• Organization settings: read and update portal configuration
• Folders: create and list content folders for better item organization

What's new in v1.6.0

• Configurable TLS verification: certificate verification is now ON by default; set MCP_TLS_VERIFY=false for self-signed Enterprise certs
• Scoped allowlists: restrict which portals, owners, groups, and service URLs the server can access via MCP_ALLOWED_* env vars

Security improvements inspired by community feedback from muend on Esri Community.

What's new in v1.5.0

• Item impact analysis: find out what breaks if you delete an item.
• Relationship explorer: map services, web maps, layers, and apps.
• Usage analytics: API calls, active users, storage trends (admin).
• Group membership audit: who is in which groups, inactive users.
• Service dependency scanner: broken links, missing data sources.
• Batch operations: update, share, delete multiple items at once.

Features

• Connect to any ArcGIS Enterprise Portal or ArcGIS Online.
• Search for items: feature services, web maps, layers, dashboards.
• Inspect item metadata, tags, and descriptions.
• Describe layers: full schema with fields, domains, subtypes, relationships, and renderer info.
• Query features with attribute filters, spatial filters, field selection, and pagination.
• Add, update, and delete features in hosted feature layers.
• Manage content: update properties, share/unshare, delete items, read web map definitions.
• Manage users: list users, get detailed profiles.
• Manage groups: list, create, and invite users.
• Publish services: upload files and publish as hosted feature services.
• Inspect GP tools: list tasks and view parameter schemas before execution.
• Run geoprocessing: execute synchronous and asynchronous GP tasks.
• Export map images: render layers as JPG/PNG/GIF/PDF/SVG.
• Portal admin: system info, license management, usage statistics.
• Batch operations: bulk delete, share, and update multiple items.
• Health check: portal system status (requires admin privileges).

Design Principles

• No arcgis Python package dependency: uses raw REST API calls via requests, so you don't need to fight with Esri's Python SDK.
• Works with Enterprise Portal AND ArcGIS Online: same tools, same API.
• Multiple auth methods: token, username/password, client_credentials, and OAuth2.
• Auto-connect: reads your .env file on startup, no manual auth needed per session.
• 2FA-friendly: works with Enterprise portals that require two-factor authentication.
• Self-signed cert friendly: handles Enterprise portals with self-signed certificates.
• Hardened: SQL injection validation on WHERE clauses, XSS protection in OAuth callbacks, automatic retry with exponential backoff.
• Scoped allowlists: optionally restrict which portals, owners, groups, and service URLs the server can access, reducing agent blast radius in production.

Installation

pip install git+https://github.com/Asem-D/arcgis-portal-mcp.git

Or clone and install from source:

git clone https://github.com/Asem-D/arcgis-portal-mcp.git
cd arcgis-portal-mcp
pip install -e .

Windows users: pywin32 is installed automatically as a platform-specific dependency.

Configuration

.env File (recommended)

Create a .env file for automatic connection on startup. A template is provided:

cp .env.example .env
# Edit .env with your portal credentials

portal_url=https://gis.example.com/portal
# Option 1: Username/password (recommended for most users)
username=your-portal-username
password=your-portal-password
# Option 2: OAuth2 app credentials (app-level, limited permissions)
# oauth_client_id=your-oauth-app-client-id
# oauth_client_secret=your-oauth-app-client-secret

The server searches for .env in this order:

1. Package directory (next to the server code) — works for source installs
2. Current working directory — works when launched from the project root
3. ~/.arcgis-portal-mcp/.env — works for pip install users

Quoted values are supported: password="my secret". Existing OS environment variables take precedence over .env values.

The server reads .env on startup and connects automatically. If username + password are provided, it uses generateToken (user-level, full permissions). Otherwise, it falls back to client_credentials (app-level, limited). No manual connect_portal call needed.

Note: The .env file is gitignored. Never commit credentials. .env.example is safe to commit.

MCP Client Configuration

For MCP clients (Claude Desktop, Cursor, etc.), the simplest setup uses a .env file:

{
  "mcpServers": {
    "arcgis-portal": {
      "command": "python",
      "args": ["-m", "arcgis_portal_mcp.server"],
      "cwd": "/path/to/arcgis-portal-mcp"
    }
  }
}

The server auto-connects from .env (searched in package dir, CWD, or ~/.arcgis-portal-mcp/). No env vars needed in the MCP config.

Alternatively, pass credentials via MCP client env vars:

{
  "mcpServers": {
    "arcgis-portal": {
      "command": "python",
      "args": ["-m", "arcgis_portal_mcp.server"],
      "env": {
        "portal_url": "https://gis.example.com/portal",
        "username": "your-portal-username",
        "password": "your-portal-password"
      }
    }
  }
}

connect_portal Tool Parameters

The connect_portal tool accepts these auth_method values:

Usage

Connect and Search

User: Search for all feature services in my portal
Agent: [calls connect_portal, then search_content with item_type="Feature Service"]

Inspect a Layer's Full Schema

User: Show me the field schema of the infrastructure layer
Agent: [calls list_layers to find the layer, then describe_layer to get fields, domains, relationships]

Query a Layer

User: Show me the first 10 parcels from the cadastral layer
Agent: [calls list_layers to find the parcel layer, then query_features with limit=10]

Inspect a GP Tool Before Running

User: What parameters does the buffer analysis tool expect?
Agent: [calls get_gp_task_info with the GP service URL to inspect parameter schemas]

Add Features

User: Add these 3 buildings to the infrastructure layer
Agent: [calls add_features with the feature service URL and JSON features]

Share a Web Map

User: Share item abc123 with the "Planning Team" group and the whole org
Agent: [calls share_item with org=true and groups=<planning-team-id>]

Read a Web Map

User: What basemap and layers are in this web map?
Agent: [calls get_item_data to read the web map JSON, summarizes basemap and operational layers]

Publish a Shapefile

User: Publish this shapefile as a hosted feature service
Agent: [calls upload_item to upload the .zip, then publish_from_item to create the service]

Run a Geoprocessing Task

User: Run the buffer analysis on the parcels layer with a 100m distance
Agent: [calls get_gp_task_info to inspect parameters, then execute_gp_task with the right inputs]

Bulk Operations

User: Delete all my draft items
Agent: [calls search_content to find items, then batch_delete_items to remove them]

Portal Administration

User: How many licenses do we have left?
Agent: [calls list_licenses to show license allocation and usage]

Available Tools (53)

Discovery and Inspection

Feature CRUD, User/Group and Content Management

Publishing, Geoprocessing, Admin and Batch

Webhooks and Logs (v1.7.0)

Collaborations, Roles and Scheduled Tasks (v1.8.0)

Authentication Methods

Enterprise portals with 2FA: Use auto (.env with client_credentials). Token auth won't work because 2FA blocks token generation. The client_credentials flow uses app-level OAuth2, no browser, no 2FA, no user interaction.

ArcGIS Online or portals without 2FA: Username/password auth via generateToken is the fastest for MCP. Put username and password in your .env file for auto-connect on startup.

Full user permissions: Use OAuth2 once to get a long-lived token, then pass it directly.

Security

TLS Certificate Verification

By default, TLS certificate verification is enabled. For Enterprise portals with self-signed certificates, disable it in your .env:

MCP_TLS_VERIFY=false

When verification is disabled, the server logs a warning. Re-enable it for production deployments with valid certificates.

Scoped Allowlists

For production use, constrain the server to specific portals, owners, groups, and service endpoints. All allowlists are optional; when unset, the server operates without restrictions (backward compatible).

# Only connect to these portals
MCP_ALLOWED_PORTAL_URLS=https://gis.example.com/portal

# Only access items owned by these users
MCP_ALLOWED_OWNERS=jsmith,mgarcia,admin

# Only share with these group IDs
MCP_ALLOWED_GROUPS=abc123,def456

# Only operate on services at these URL prefixes
MCP_ALLOWED_SERVICE_URLS=https://gis.example.com/portal/sharing/rest/services

Operations targeting resources outside the allowlist are rejected with a clear error message. For batch operations, items outside the owner allowlist are skipped with per-item reporting.

What's Next

Here's what we're working on for upcoming releases:

• Collaboration management: list, sync, and manage distributed collaborations (v1.8.0)
• Role privilege management: get and set role privileges (v1.8.0)
• Scheduled tasks: list and filter user scheduled tasks with taskState (v1.8.0)
• Server federation: list, validate, federate, and unfederate servers (v1.9.0)
• Feature service sync: createReplica, offline workflows (v2.0.0)

If any of these would solve a problem you're facing, open an issue and let us know. We prioritize based on real-world needs.

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check arcgis_portal_mcp/

License

MIT. See LICENSE.

Author

Asem Daaboul ([email protected])