carvelink-mcp

MCP (Model Context Protocol) server for CarveLink. Lets AI agents read and write your bio pages — create pages, add blocks, update themes, pull analytics, upload images.

Works with any MCP-compatible client: Claude Desktop, Claude Code, Cursor, and others.

Install

npm install -g carvelink-mcp

Or run on demand via npx carvelink-mcp (see client configs below).

Get an API key

1. Sign in at carvelink.com
2. Open Billing → API Keys
3. Click Create API Key, copy the cv_live_... value (you won't see it again)

API keys inherit your account's tier permissions. Rate limit: 60 requests/minute per key.

Configure your client

Claude Desktop

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

{
  "mcpServers": {
    "carvelink": {
      "command": "npx",
      "args": ["-y", "carvelink-mcp"],
      "env": {
        "CARVELINK_API_KEY": "cv_live_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. You should see the carvelink server in the MCP indicator.

Claude Code

Add to ~/.claude/mcp.json or your project's .mcp.json:

{
  "mcpServers": {
    "carvelink": {
      "command": "npx",
      "args": ["-y", "carvelink-mcp"],
      "env": {
        "CARVELINK_API_KEY": "cv_live_your_key_here"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "carvelink": {
      "command": "npx",
      "args": ["-y", "carvelink-mcp"],
      "env": { "CARVELINK_API_KEY": "cv_live_your_key_here" }
    }
  }
}

Tools

Pages

• list_pages — list all bio pages
• get_page — fetch one page with blocks and settings
• create_page — create a new page (title, slug, description)
• update_page — change title, slug, or description
• delete_page — delete a page permanently

Blocks

• list_block_types — list all available block types with required fields
• get_block_schema — get the full content schema for a specific block type
• list_blocks — list blocks on a page
• add_block — add a block to a page (see schema tools above for content shape)
• update_block — change a block's content or visibility
• delete_block — remove a block
• reorder_blocks — set block display order

Theming

• update_theme — change theme preset or apply overrides

Analytics & account

• get_analytics — views, clicks, CTR, device breakdown, top links
• get_account — email, subscription tier
• get_usage — page and product counts
• get_earnings — digital product and tip income
• list_products — digital products in your store

Assets

• upload_image — upload an image (base64) and get a public URL for use in blocks

Block type discovery

There are 23 block types. Rather than memorizing their schemas, agents should call the discovery tools:

list_block_types       → [{type, description, required_fields}, ...]
get_block_schema(type) → {type, description, fields, example, notes}

Example workflow: "Add a testimonial block to my Services page"

1. list_block_types → agent sees testimonial exists
2. get_block_schema("testimonial") → agent learns it needs testimonials: [{id, quote, author, ...}] and display_mode: 'single' | 'carousel'
3. add_block(page_id, type: "testimonial", content: {...})

Environment variables

| Variable | Required | Default | Purpose | |----------|----------|---------|---------| | CARVELINK_API_KEY | yes | — | Your cv_live_... API key | | CARVELINK_API_URL | no | CarveLink production | Override for self-hosted / dev |

Troubleshooting

"CARVELINK_API_KEY environment variable is required" — the key isn't being passed to the MCP server. Check your client config's env block.

"Invalid API key" — the key may have been revoked. Generate a new one in Billing → API Keys.

"Rate limit exceeded" — you've hit 60 requests in the last minute. Wait or add a second key.

Tool not appearing — restart your MCP client after editing its config. Check the logs for startup errors.

Development

npm install
npm run build
CARVELINK_API_KEY=cv_live_xxx node dist/index.js

To point at a local or staging API:

CARVELINK_API_URL=http://localhost:54321/functions/v1/api-v1 CARVELINK_API_KEY=cv_live_xxx node dist/index.js

License

MIT