# Are.na MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)

A Model Context Protocol server that lets AI agents interact with [Are.na](https://are.na) — the platform for creative research and knowledge curation. Built for the **Are.na API v3**.

- **Search and browse** channels, blocks, users, and groups
- **Create and manage** channels and blocks
- **Connect content** across channels
- **Comment** on blocks
- **Explore networks** of related content
- **Visual content support** — vision analysis for image blocks

**No API token needed** for browsing — only required for write operations.

## Installation

```bash
pip install mcp httpx pydantic python-dotenv
```

For write access, add your Are.na token:

```bash
# Get one at: https://are.na/settings/personal-access-tokens
echo "ARENA_ACCESS_TOKEN=your_token_here" > .env
```

## Setup with Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "arena": {
      "command": "python",
      "args": ["/absolute/path/to/arena_mcp.py"]
    }
  }
}
```

## Setup with Claude Code

```bash
claude mcp add arena python /absolute/path/to/arena_mcp.py
```

## Response Formats

All tools support three response formats via the `response_format` parameter:

| Format | Default | Description |
|--------|---------|-------------|
| `compact` | Yes | One line per item with all IDs. Best for agents. |
| `markdown` | | Detailed multi-line view. Good for reading. |
| `json` | | Clean JSON (image blobs stripped by default). |

Compact format example:
```
[Page 1/3 | 72 total | more: page=2]
id:12345 | Image | conn:67890 | "Architecture Photo" | https://example.com | @username
id:12346 | Text | conn:67891 | "Research Notes" | @username | [First 100 chars of content...]
id:12347 | Link | conn:67892 | "Reference Article" | https://example.com/article | @username
```

## Available Tools

### Search
- `arena_search` — Unified search across blocks, channels, users, groups. Supports type/scope/sort filters.

### Channels
- `arena_get_channel` — Channel metadata
- `arena_get_channel_contents` — Paginated contents with sorting
- `arena_get_channel_connections` — Channels connected to this channel
- `arena_get_channel_followers` — Channel followers
- `arena_create_channel` — Create a channel
- `arena_update_channel` — Update title, visibility, description
- `arena_delete_channel` — Delete a channel (irreversible)

### Blocks
- `arena_get_block` — Block details with optional vision support for images
- `arena_get_block_comments` — Comments on a block
- `arena_get_block_connections` — Channels containing a block
- `arena_create_block` — Create a block (URL or text) and connect to channels
- `arena_update_block` — Update title, description, content

### Comments
- `arena_create_comment` — Comment on a block (supports @mentions)
- `arena_delete_comment` — Delete a comment

### Connections
- `arena_create_connection` — Connect a block or channel to channel(s)
- `arena_delete_connection` — Remove a connection
- `arena_bulk_delete_connections` — Delete up to 50 connections at once
- `arena_move_connection` — Reorder items within a channel

### Users
- `arena_get_me` — Current authenticated user
- `arena_get_user` — User profile
- `arena_get_user_contents` — Blocks and channels by a user
- `arena_get_user_following` — Who/what a user follows (filterable by type)
- `arena_get_user_followers` — User's followers

### Groups
- `arena_get_group` — Group profile
- `arena_get_group_contents` — Blocks and channels by a group

## License

MIT License — see [LICENSE](LICENSE) file for details.

## Links

- [Are.na](https://are.na)
- [Are.na API Documentation](https://www.are.na/developers)
- [Model Context Protocol](https://modelcontextprotocol.io)