@8ux-co/eelzap-mcp-server

Connect your AI assistant to Eel Zap CMS. Create collections, manage content, upload media, and publish — all through natural language.

Works with Claude Code, Cursor, VS Code, Codex, and Claude Desktop.

Quick Start

With the CLI (recommended):

npx @8ux-co/eelzap-mcp-server install

With Claude Code:

claude mcp add --transport stdio eelzap \
  --env EELZAP_API_KEY=secret_your_key_here \
  -- npx -y @8ux-co/eelzap-mcp-server

For other tools, see the Installation Guides below.

Installation Guides

Claude Code

CLI method:

npx @8ux-co/eelzap-mcp-server install --tool claude-code

Manual method — Project scope (.mcp.json):

Create .mcp.json in your project root:

{
  "mcpServers": {
    "eelzap": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@8ux-co/eelzap-mcp-server"],
      "env": {
        "EELZAP_API_KEY": "secret_your_key_here"
      }
    }
  }
}

Manual method — User scope (~/.claude.json):

Add to the mcpServers section in ~/.claude.json:

{
  "mcpServers": {
    "eelzap": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@8ux-co/eelzap-mcp-server"],
      "env": {
        "EELZAP_API_KEY": "secret_your_key_here"
      }
    }
  }
}

Using claude mcp add:

claude mcp add --transport stdio eelzap \
  --env EELZAP_API_KEY=secret_your_key_here \
  -- npx -y @8ux-co/eelzap-mcp-server

Cursor

CLI method:

npx @8ux-co/eelzap-mcp-server install --tool cursor

Manual method — Project scope:

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "eelzap": {
      "command": "npx",
      "args": ["-y", "@8ux-co/eelzap-mcp-server"],
      "env": {
        "EELZAP_API_KEY": "secret_your_key_here"
      }
    }
  }
}

Manual method — Global scope:

Create or edit ~/.cursor/mcp.json with the same structure.

VS Code

CLI method:

npx @8ux-co/eelzap-mcp-server install --tool vscode

Manual method:

Create .vscode/mcp.json in your project root:

{
  "servers": {
    "eelzap": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@8ux-co/eelzap-mcp-server"],
      "env": {
        "EELZAP_API_KEY": "secret_your_key_here"
      }
    }
  }
}

Important: VS Code uses "servers" as the top-level key, not "mcpServers".

Codex

CLI method:

npx @8ux-co/eelzap-mcp-server install --tool codex

Manual method:

Add to ~/.codex/config.toml (or .codex/config.toml for project scope):

[mcp_servers.eelzap]
command = "npx"
args = ["-y", "@8ux-co/eelzap-mcp-server"]
enabled = true

[mcp_servers.eelzap.env]
EELZAP_API_KEY = "secret_your_key_here"

Claude Desktop

CLI method:

npx @8ux-co/eelzap-mcp-server install --tool claude-desktop

Manual method:

Edit the config file at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

Add to the mcpServers section:

{
  "mcpServers": {
    "eelzap": {
      "command": "npx",
      "args": ["-y", "@8ux-co/eelzap-mcp-server"],
      "env": {
        "EELZAP_API_KEY": "secret_your_key_here"
      }
    }
  }
}

Restart Claude Desktop after saving.

CLI Commands

Command	Description
npx @8ux-co/eelzap-mcp-server install	Interactive setup for any supported tool
npx @8ux-co/eelzap-mcp-server switch-key	Change the API key for an existing installation
npx @8ux-co/eelzap-mcp-server uninstall	Remove the eelzap entry from a tool's config
npx @8ux-co/eelzap-mcp-server status	Show all detected installations and their connection status
npx @8ux-co/eelzap-mcp-server doctor	Diagnose common configuration issues

Examples:

# Install with flags (non-interactive):
npx @8ux-co/eelzap-mcp-server install \
  --tool claude-code \
  --scope project \
  --api-key secret_xxx

# Update the API key for a specific tool:
npx @8ux-co/eelzap-mcp-server switch-key --tool cursor

# Check what's configured and whether it's working:
npx @8ux-co/eelzap-mcp-server status

# Run diagnostics:
npx @8ux-co/eelzap-mcp-server doctor

Configuration

Environment Variables

Variable	Required	Default	Description
EELZAP_API_KEY	Yes	—	Your API key. Starts with secret_ (full access) or public_ (read-only). Get it from your Eel Zap dashboard under Settings > API Keys.
EELZAP_BASE_URL	No	https://api.eelzap.com	API base URL. Override for self-hosted or local development.
EELZAP_PATH_PREFIX	No	/v1	Path prefix. Set to /api/public/v1 for local dev against the Next.js dev server.

API Key Types

Key prefix	Access level	Use case
secret_	Full read/write	Creating content, managing collections, uploading media, publishing
public_	Read-only	Querying published content via the delivery API only

For MCP server usage, you almost always want a secret key since the whole point is to manage content through your AI assistant.

Local Development

If you're running the CMS locally:

"env": {
  "EELZAP_API_KEY": "secret_your_key",
  "EELZAP_BASE_URL": "http://localhost:5041",
  "EELZAP_PATH_PREFIX": "/api/public/v1"
}

Available Tools

Sites (1 tool)

Tool	Description
get_site	Get the current site associated with your API key

Collections (5 tools)

Tool	Description
list_collections	List all collections in the site
get_collection	Get a collection by ID
create_collection	Create a new collection
update_collection	Update a collection's name or key
delete_collection	Delete a collection and all its items

Collection Fields (5 tools)

Tool	Description
list_collection_fields	List all fields in a collection
create_collection_field	Add a new field to a collection
update_collection_field	Update a field's configuration
delete_collection_field	Remove a field from a collection
reorder_collection_fields	Change the display order of fields

Collection Sections (4 tools)

Tool	Description
list_collection_sections	List all sections in a collection
create_collection_section	Create a new section to group fields
update_collection_section	Update a section's name
delete_collection_section	Delete a section

Items (7 tools + 7 versioning tools)

Tool	Description
list_items	List items in a collection (with pagination and search)
get_item	Get a single item by ID
create_item	Create a new item in a collection
update_item	Update an item's field values
delete_item	Delete an item
publish_item	Publish an item (makes it available via delivery API)
unpublish_item	Unpublish an item

Item Versioning (7 tools)

Tool	Description
list_item_versions	List version history for an item
get_item_version	Get details of a specific version
create_item_draft	Create a draft from the current published version
update_item_draft	Update draft field values
discard_item_draft	Discard the current draft (non-destructive)
publish_item_draft	Publish the draft as the live version
rollback_item_version	Create a draft from a historical version

Documents (5 tools + 7 versioning tools)

Tool	Description
list_documents	List all documents (singletons like homepage, about page)
get_document	Get a document by ID
create_document	Create a new document
update_document	Update a document's name or key
delete_document	Delete a document

Document Fields (5 tools)

Tool	Description
list_document_fields	List all fields in a document
create_document_field	Add a new field to a document
update_document_field	Update a field's configuration
delete_document_field	Remove a field from a document
reorder_document_fields	Change the display order of fields

Document Sections (4 tools)

Tool	Description
list_document_sections	List all sections in a document
create_document_section	Create a new section to group fields
update_document_section	Update a section's name
delete_document_section	Delete a section

Document Values (2 tools)

Tool	Description
get_document_values	Get all field values for a document
set_document_values	Set field values for a document

Document Publishing (2 tools)

Tool	Description
publish_document	Publish a document
unpublish_document	Unpublish a document

Document Versioning (7 tools)

Tool	Description
list_document_versions	List version history for a document
get_document_version	Get details of a specific version
create_document_draft	Create a draft from the current published version
update_document_draft	Update draft field values
discard_document_draft	Discard the current draft (non-destructive)
publish_document_draft	Publish the draft as the live version
rollback_document_version	Create a draft from a historical version

Media (7 tools)

Tool	Description
list_media	List all media assets
get_media	Get a media asset by ID
upload_media_from_url	Upload media from a URL
update_media	Update media metadata (alt text, title)
delete_media	Delete a media asset
publish_media	Publish a media asset
unpublish_media	Unpublish a media asset

SEO (4 tools)

Tool	Description
get_item_seo	Get SEO metadata for a collection item
set_item_seo	Set SEO metadata for a collection item, including Schema.org structured data
get_document_seo	Get SEO metadata for a document
set_document_seo	Set SEO metadata for a document, including Schema.org structured data

Delivery API (5 tools)

Tool	Description
delivery_list_collections	List published collections (public API)
delivery_get_collection	Get a published collection (public API)
delivery_list_items	List published items in a collection (public API)
delivery_get_item	Get a published item (public API)
delivery_get_document	Get a published document (public API)

What Can You Do?

Once connected, try asking your AI assistant:

Content Creation

• "Create a blog collection with title, content, author, and featured image fields"
• "Add 5 blog posts about web development best practices"
• "Create an About page document with hero title, description, and team section"

Content Management

• "List all my collections and their field schemas"
• "Update the hero title on my homepage to 'Build faster with AI'"
• "Publish all draft items in the blog collection"

Media

• "Upload this image from URL and set it as the featured image for my latest blog post"
• "List all media assets and show me which ones are unpublished"

SEO

• "Set SEO metadata for all blog posts — generate meta titles and descriptions based on the content"
• "Check which items are missing SEO metadata"

Site Discovery

• "Show me the structure of my site — all collections, documents, and their fields"
• "What content types do I have? List everything."

Content Delivery

• "Fetch my published blog posts and show me what the delivery API returns"
• "Check if the homepage document is published and what data it serves"

Troubleshooting

"EELZAP_API_KEY is required"

The server can't find your API key. Make sure it's set in the env section of your MCP config (all tools, including Codex via [mcp_servers.eelzap.env]).

"Connection refused" or "ECONNREFUSED"

The server can't reach the API. Check:

• Your EELZAP_BASE_URL is correct (default: https://api.eelzap.com)
• If using local dev, ensure the CMS app is running on the expected port

"401 Unauthorized"

Your API key is invalid or expired. Generate a new one from the Eel Zap dashboard (Settings > API Keys) and run eelzap-mcp switch-key.

"403 Forbidden"

You're using a public key (public_) for a write operation. Switch to a secret key (secret_).

Server not appearing in your tool

• Claude Code: Restart Claude Code or run /mcp to check server status
• Cursor: Restart Cursor; check Settings > Tools & MCP for server status
• VS Code: Check the MCP panel; try "MCP: List Servers" from the command palette
• Codex: Restart Codex; ensure the TOML config is at ~/.codex/config.toml
• Claude Desktop: Fully quit and reopen Claude Desktop (config changes require restart)

Tools not loading / "No tools available"

The server starts but tools aren't registered. Run eelzap-mcp doctor to diagnose, or check the server logs for errors during startup.

Development

git clone https://github.com/8ux-co/eelzap-mcp-server.git
cd eelzap-mcp-server
npm install
npm run build
npm test

Run locally during development:

EELZAP_API_KEY=secret_... npx tsx src/index.ts

Test with MCP Inspector:

EELZAP_API_KEY=secret_... npx @modelcontextprotocol/inspector npx tsx src/index.ts