Metadata-Version: 2.4
Name: agent-labbook
Version: 0.13.2
Summary: Notion auth and project binding for Codex, Claude Code, and other MCP clients.
Author-email: Binbin Shen <binbinsh@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/binbinsh/agent-labbook
Project-URL: Repository, https://github.com/binbinsh/agent-labbook
Keywords: codex,claude-code,mcp,notion,oauth
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<2,>=1.26.0
Dynamic: license-file

# agent-labbook

Agent Labbook is the Notion connection layer for Codex, Claude Code, and other MCP clients. It starts Notion auth, lets you choose which pages or data sources belong to a project, stores tokens and bindings locally in `.labbook/`, and returns the API context your agent needs to call Notion directly.

Use it when you want to:

- connect a repo to specific Notion pages or data sources for an agent
- let an agent read or update project docs and data sources through the official Notion API
- avoid building your own Notion auth wrapper for coding agents

It is not a full Notion SDK. After setup, your agent should use the official Notion API directly.

## Install

Use Agent Labbook as a local MCP server for the current project.

Requirements:

- Python 3.10 or newer
- `uv`
- a Codex, Claude Code, or other MCP-capable client that can run a local MCP server

Recommended setup:

```bash
codex mcp add labbook -- uvx agent-labbook mcp
claude mcp add --scope project labbook -- uvx agent-labbook mcp
```

- or use the checked-in [`.mcp.json`](./.mcp.json) when the repository itself is the MCP source

## Typical Flow

1. Run `notion_status`.
2. Run `notion_auth_browser`, or `notion_start_headless_auth` if connecting through SSH or another headless environment.
3. Choose the Notion pages or data sources for this project.
4. Run `notion_get_api_context`.
5. Use the returned token, headers, and resource IDs with the official Notion API.

## Hosted Backend

The default backend is `https://labbook.superplanner.net`. It is privacy-friendly: it handles OAuth and token refresh without keeping your project tokens or Notion content in server-side storage. Long-lived tokens and bindings stay local in `.labbook/`.

If you want to self-host it, see [`docs/self-host.md`](./docs/self-host.md).

## Notes

- `.labbook/` should never be committed
- this repo handles auth and project binding, not general Notion API wrapping
