# CloudMindMaps MCP Server

[![npm version](https://img.shields.io/npm/v/cloudmindmaps-mcp.svg)](https://www.npmjs.com/package/cloudmindmaps-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

Let Claude — and any other [Model Context Protocol](https://modelcontextprotocol.io) client — create, browse, and read mind maps directly on **[cloudmindmaps.app](https://cloudmindmaps.app)**. Maps use the open FreeMind/Freeplane `.mm` format, so anything you make here also opens in those desktop apps.

Just ask:

> *"Turn these meeting notes into a mind map."*
> *"Make a mind map of the pros and cons of microservices."*
> *"List my mind maps and show me the roadmap one."*

Claude structures the ideas, this server saves the map, and you get a shareable link.

## Tools

| Tool | What it does |
|---|---|
| **`create_mindmap_from_outline`** | **Recommended.** The AI supplies a nested outline; the server generates valid `.mm` XML (IDs, balanced branches, escaping) and saves it. |
| `create_mindmap` | Create a map from raw CloudMindMaps `.mm` XML (for power users who need clouds, edges, connectors, rich HTML nodes). |
| `list_mindmaps` | List maps you own or that are shared with you. |
| `get_mindmap` | Read a map's details and full `.mm` XML by ID. |

Plus a prompt, **`convert_to_mindmap`**, that turns any pasted content into a well-structured map in one step.

## Quick start

### 1. Get your CloudMindMaps API key

Sign in at [cloudmindmaps.app](https://cloudmindmaps.app), open your browser console, and run:

```js
const token = await firebase.auth().currentUser.getIdToken();
const res = await fetch("https://cloudmindmaps.app/api/keys", {
  method: "POST",
  headers: { Authorization: `Bearer ${token}` },
});
console.log("Your API key:", (await res.json()).key);
```

Copy the key — it's shown only once. Re-running the command regenerates it (and revokes the old one).

### 2. Add the server to your MCP client

No install needed — `npx` fetches and runs it. Just add the config below and drop in your key.

**Claude Desktop** — edit `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "cloudmindmaps": {
      "command": "npx",
      "args": ["-y", "cloudmindmaps-mcp"],
      "env": { "CLOUDMINDMAPS_API_KEY": "YOUR_API_KEY_HERE" }
    }
  }
}
```

**Claude Code** (CLI):

```bash
claude mcp add cloudmindmaps --env CLOUDMINDMAPS_API_KEY=YOUR_API_KEY_HERE -- npx -y cloudmindmaps-mcp
```

**Cursor / other MCP clients** — same shape: command `npx`, args `["-y", "cloudmindmaps-mcp"]`, env `CLOUDMINDMAPS_API_KEY`.

### 3. Restart your client

You'll see the four tools appear. Ask Claude to make a mind map and it will reply with a link to open on cloudmindmaps.app.

## Configuration

| Env var | Required | Default | Description |
|---|---|---|---|
| `CLOUDMINDMAPS_API_KEY` | ✅ | — | Your API key from step 1. |
| `CLOUDMINDMAPS_API_URL` | — | `https://cloudmindmaps.app` | Override for self-hosted / staging. |
| `CLOUDMINDMAPS_TIMEOUT_MS` | — | `30000` | Per-request timeout in milliseconds. |

## Running from source (development)

```bash
cd mcp-server
npm install
CLOUDMINDMAPS_API_KEY=YOUR_KEY node index.js
```

Then point your client at `node /absolute/path/to/mcp-server/index.js` instead of `npx`.

## Revoking your key

```js
const token = await firebase.auth().currentUser.getIdToken();
await fetch("https://cloudmindmaps.app/api/keys", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${token}` },
});
```

## Links

- Web app: https://cloudmindmaps.app
- Setup guide: https://cloudmindmaps.app/mcp
- `.mm` format spec: https://cloudmindmaps.app/prompt-convert-to-mm.md

## License

MIT © Jan Rezab / CloudMindMaps