Metadata-Version: 2.4
Name: agentbrain-mcp
Version: 0.1.0
Summary: MCP server for Agent Brain — cross-source personal memory for any MCP-capable AI client (Claude Code, Claude Desktop, Cursor, Windsurf)
Project-URL: Homepage, https://agentbrain.ch
Project-URL: Documentation, https://agentbrain.ch/docs/mcp
Project-URL: Repository, https://github.com/AgentBrainHQ/agentbrain-mcp
Author-email: Thesh Sritharan <hello@agentbrain.ch>
License: MIT
License-File: LICENSE
Keywords: ai,claude,cursor,llm,mcp,memory,personal-brain
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.2.0
Requires-Dist: pydantic>=2.6.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.3; extra == 'dev'
Provides-Extra: http
Requires-Dist: starlette>=0.37.0; extra == 'http'
Requires-Dist: uvicorn>=0.30.0; extra == 'http'
Description-Content-Type: text/markdown

# agentbrain-mcp

MCP server that gives any MCP-capable AI client (Claude Code, Claude Desktop, Cursor, Windsurf) access to your personal Agent Brain — cross-source memory that persists across tools, conversations, and devices.

Status: [status.agentbrain.ch](https://status.agentbrain.ch) · Changelog: [CHANGELOG.md](./CHANGELOG.md) · License: MIT

## What it does

Three tools, registered as native MCP tools:

- **`brain_recall(query, limit)`** — search your Brain for relevant memories
- **`brain_store(content, memory_type, source_trust)`** — persist a memory
- **`brain_status()`** — health check

The server is single-user: each install is bound to one workspace via env vars. If you have multiple brains (work/personal), run multiple instances.

## Install

```bash
pip install agentbrain-mcp
```

Or from source:

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

## Configure

Get your API key and workspace id from <https://agentbrain.ch/settings>. Export them:

```bash
export BRAIN_API_KEY='brain_xxxxxxxxxxxx'
export BRAIN_WORKSPACE_ID='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
```

Optional:

| Env var | Default | Purpose |
|---|---|---|
| `BRAIN_URL` | `https://api.agentbrain.ch` | Brain API base URL (override for self-hosted) |
| `BRAIN_TIMEOUT_S` | `45` | Request timeout in seconds |
| `BRAIN_DEFAULT_LIMIT` | `10` | Default `limit` for `brain_recall` when not provided |

## Use with Claude Code

```bash
claude mcp add agentbrain --scope user \
  -e BRAIN_API_KEY=$BRAIN_API_KEY \
  -e BRAIN_WORKSPACE_ID=$BRAIN_WORKSPACE_ID \
  -- agentbrain-mcp
```

Then in any Claude Code session:

```
> brain_recall("previous decisions on auth")
```

## Use with Cursor / Windsurf

Add to your MCP config (`~/.cursor/mcp.json` or equivalent):

```json
{
  "mcpServers": {
    "agentbrain": {
      "command": "agentbrain-mcp",
      "env": {
        "BRAIN_API_KEY": "brain_xxxxxxxxxxxx",
        "BRAIN_WORKSPACE_ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }
    }
  }
}
```

## Use with Claude Desktop

Same JSON as Cursor, in `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows).

## Test it runs

```bash
# Should print a config error if env not set — no network required
agentbrain-mcp
```

With env set it will wait for an MCP client to connect on stdio.

## Run over HTTP / SSE

For Claude Desktop Remote Connectors or a self-hosted endpoint:

```bash
# Streamable HTTP (recommended for new deployments)
agentbrain-mcp --http

# Legacy SSE
agentbrain-mcp --sse
```

Single-tenant: the endpoint is bound to the API key and workspace id of the process that started it. Host behind your own reverse proxy (Traefik, Caddy, nginx) for TLS. Multi-tenant hosting (one endpoint, many users with different keys) requires a separate server and is not in scope here.

## Development

```bash
pip install -e ".[dev]"
pytest
```

Build the package:

```bash
pip install build twine
python -m build
twine check dist/*
```

## License

MIT — see [LICENSE](./LICENSE).
