Premium Feature

MCP Server Documentation

Connect AI assistants like Claude Desktop, Cursor, and other MCP-compatible clients to manage your ListMaker lists programmatically using the Model Context Protocol.

Quick Start

1. Generate an API Key

Go to Settings > API Keys and create a new key. Choose a name, select permissions, and copy the key. The full key is only shown once.

2. Configure Your MCP Client

Add ListMaker as an MCP server in your client's configuration. The endpoint is:

https://listmaker.kohnkenet.de/api/mcp

3. Start Using It

Once configured, your AI assistant discovers ListMaker tools automatically. Try prompts like:

• "Create a new list called 'Project Ideas'"
• "Show me all my lists"
• "Add 5 items to my 'Books to Read' list"
• "Export my 'Team Votes' list as CSV"

Client Configuration Examples

Claude Desktop

Edit your claude_desktop_config.json file:

claude_desktop_config.json

{
  "mcpServers": {
    "listmaker": {
      "url": "https://listmaker.kohnkenet.de/api/mcp",
      "headers": {
        "Authorization": "Bearer lm_your-api-key-here"
      }
    }
  }
}

Claude Code

Add to your project or global MCP settings:

.mcp.json

{
  "mcpServers": {
    "listmaker": {
      "type": "streamable-http",
      "url": "https://listmaker.kohnkenet.de/api/mcp",
      "headers": {
        "Authorization": "Bearer lm_your-api-key-here"
      }
    }
  }
}

Cursor

Go to Settings > MCPin Cursor, click "Add new MCP server", select "Streamable HTTP", and enter the URL and authorization header:

URL: https://listmaker.kohnkenet.de/api/mcp
Header: Authorization: Bearer lm_your-api-key-here

Windsurf

Add to your ~/.codeium/windsurf/mcp_config.json:

mcp_config.json

{
  "mcpServers": {
    "listmaker": {
      "serverUrl": "https://listmaker.kohnkenet.de/api/mcp",
      "headers": {
        "Authorization": "Bearer lm_your-api-key-here"
      }
    }
  }
}

Authentication

All requests require an API key sent as a Bearer token in the Authorization header.

Header	`Authorization: Bearer lm_...`
Key prefix	`lm_`
Key format	`lm_` + 54 random characters
Storage	SHA-256 hashed (never stored in plain text)

Keys are tied to your account and premium subscription. If your subscription lapses, MCP requests will be rejected until reactivated.

Permissions

All Permissions

Permission	Description
`read_lists`	View lists, items, tags, and search
`create_lists`	Create new lists
`manage_items`	Add, update, and delete items
`vote`	Cast and remove votes
`comment`	Add and delete comments
`export`	Export list data as JSON or CSV
`manage_settings`	Update list settings, delete lists, manage tags

Presets

Preset	Permissions
Read-only	`read_lists`
Read-write	`read_lists, create_lists, manage_items, vote, comment`
Full access	`All 7 permissions`

By default, keys have globalaccess to all your lists. You can restrict a key to specific lists by choosing "Specific lists" scope when creating or editing a key.

Tools Reference

17 tools across 6 categories. Each tool requires a specific permission.

List Management

Tool	Description	Permission
`list_create`	Create a new list	`create_lists`
`list_get`	Get list details by slug	`read_lists`
`list_search`	Search or list your lists	`read_lists`
`list_update`	Update list settings	`manage_settings`
`list_delete`	Delete a list you own	`manage_settings`

Item Management

Tool	Description	Permission
`item_add`	Add an item to a list	`manage_items`
`item_update`	Update an item	`manage_items`
`item_delete`	Delete an item	`manage_items`
`list_items`	Get all items with vote counts	`read_lists`

Voting

Tool	Description	Permission
`vote_cast`	Cast an upvote or downvote	`vote`
`vote_remove`	Remove your vote	`vote`
`star_rate`	Rate with 1-5 stars	`vote`

Comments

Tool	Description	Permission
`comment_add`	Add a comment to an item	`comment`
`comment_delete`	Delete your comment	`comment`

Tool	Description	Permission
`tag_list`	Get all tags for a list	`read_lists`
`tag_set`	Set tags on an item	`manage_settings`

Export

Tool	Description	Permission
`list_export`	Export as JSON or CSV	`export`

Resources

Read-only data endpoints using the listmaker:// URI scheme. These return JSON and require the read_lists permission.

URI	Description
`listmaker://lists`	All your lists
`listmaker://lists/{slug}`	Full details for a specific list
`listmaker://lists/{slug}/items`	All items in a list with vote counts
`listmaker://lists/{slug}/items/{item_id}`	Single item with comments and votes
`listmaker://lists/{slug}/tags`	All tags for a list

Prompts

Reusable templates that guide AI assistants through common workflows.

`get-started`

An introduction to ListMaker's MCP server. Explains available tools, resources, and suggested workflows.

`manage-list`

A template for performing operations on a specific list. Accepts optional arguments:

slug — The list to manage
action — One of overview, add-items, check-results, or export

Rate Limits

Window	Limit
Per minute	60 requests
Per day	5,000 requests

Rate-limited responses return HTTP 429 with a Retry-After header.

Error Codes

Standard JSON-RPC error codes:

Code	Meaning
`-32600`	Invalid JSON or malformed request
`-32601`	Method not found
`-32602`	Invalid parameters
`-32603`	Internal server error
`-32001`	Unauthorized — missing or invalid API key
`-32002`	Forbidden — insufficient permissions
`-32029`	Rate limit exceeded

Ready to connect?

Generate an API key and start managing your lists with AI.

Go to API Keys