# MindMeister MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that connects Claude to the [MindMeister API v2](https://www.mindmeister.com/api), enabling AI-powered mind map management directly from Claude Desktop or Claude Code.

## What is MCP?

MCP is an open standard that lets AI assistants like Claude interact with external tools and services. This server exposes MindMeister operations as MCP tools that Claude can call during conversations.

## Available Tools

| Tool | Description |
|------|-------------|
| `mindmeister_get_user` | Get the authenticated user's profile |
| `mindmeister_get_map` | Get metadata for a specific map (JSON) |
| `mindmeister_list_maps` | List maps with pagination |
| `mindmeister_export_map` | Export a map as PDF, DOCX, PPTX, RTF, or image |
| `mindmeister_get_map_image` | Get the image/thumbnail of a map |
| `mindmeister_list_rights` | List sharing permissions for a map |
| `mindmeister_get_preferences` | Get user preferences |

## Prerequisites

- Python 3.10+
- A MindMeister account with API access
- A Personal Access Token from MindMeister

## Getting Your API Token

1. Log in to [MindMeister](https://www.mindmeister.com)
2. Go to **Account** → **API** → **Personal Access Tokens**
3. Create a new token with the scopes you need:
   - `mindmeister.readonly` — for read-only access
   - `mindmeister` — for full access
4. Copy the token

## Installation

### Option 1: Install from source

```bash
git clone https://github.com/conexaoarteiro/mindmeister-mcp.git
cd mindmeister-mcp
pip install -e .
```

### Option 2: Install directly from GitHub

```bash
pip install git+https://github.com/conexaoarteiro/mindmeister-mcp.git
```

### Option 3: Manual setup

```bash
git clone https://github.com/conexaoarteiro/mindmeister-mcp.git
cd mindmeister-mcp
pip install -r requirements.txt
```

## Configuration

Set your MindMeister API token as an environment variable:

```bash
export MINDMEISTER_API_TOKEN="your_personal_access_token_here"
```

Or create a `.env` file based on `.env.example`:

```bash
cp .env.example .env
# Edit .env and add your token
```

## Usage with Claude Desktop

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mindmeister": {
      "command": "python",
      "args": ["-m", "mindmeister_mcp.server"],
      "env": {
        "MINDMEISTER_API_TOKEN": "your_personal_access_token_here"
      }
    }
  }
}
```

If you installed with `pip install -e .`, you can also use:

```json
{
  "mcpServers": {
    "mindmeister": {
      "command": "mindmeister-mcp",
      "env": {
        "MINDMEISTER_API_TOKEN": "your_personal_access_token_here"
      }
    }
  }
}
```

### Config file location

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

## Usage with Claude Code

```bash
claude mcp add mindmeister -- python -m mindmeister_mcp.server
```

Then set the environment variable before running Claude Code:

```bash
export MINDMEISTER_API_TOKEN="your_token"
claude
```

## Example Conversations

Once configured, you can ask Claude things like:

- *"Show me my MindMeister maps"*
- *"Get the details of map 1234567890"*
- *"Export map 1234567890 as PDF"*
- *"Who has access to map 1234567890?"*
- *"What are my MindMeister account details?"*

## Development

```bash
# Clone and install in dev mode
git clone https://github.com/conexaoarteiro/mindmeister-mcp.git
cd mindmeister-mcp
pip install -e ".[dev]"

# Run the server directly
python -m mindmeister_mcp.server
```

## Project Structure

```
mindmeister-mcp/
├── README.md
├── pyproject.toml
├── requirements.txt
├── .env.example
├── .gitignore
└── src/
    └── mindmeister_mcp/
        ├── __init__.py
        ├── server.py      # FastMCP server with all tools
        ├── client.py       # Async HTTP client for MindMeister API v2
        └── models.py       # Pydantic input validation models
```

## API Coverage

This server targets MindMeister API v2 (`https://www.mindmeister.com/api/v2/`). The following endpoints are covered:

- `GET /users/me` — user profile
- `GET /maps/{id}` — map metadata
- `GET /maps` — list maps
- `GET /maps/{id}` (with Accept header) — export as PDF/DOCX/PPTX/RTF/image
- `GET /map_images/{id}` — map image
- `GET /maps/{id}/rights` — map permissions
- `GET /users/me/preferences` — user preferences

## License

MIT