notioncode_mcp

# notioncode_mcp Local agent bridge between **Notion AI** models and popular coding environments: OpenCode, Claude Code, and Codex CLI. Allows using Notion AI models instead of standard OpenAI/Anthropic models in these tools — without OpenAI or Anthropic subscription. **Supported models:** - `notion-fable/fable-5` (Fable 5, by default) - `notion-fable/gpt-5.6-sol` (GPT-5.6 Sol) The agent can read, create, and edit files under `/root`, execute shell commands, and run checks. ## How it works ### Architecture ``` OpenCode / Claude Code / Codex CLI │ │ HTTP (OpenAI or Anthropic API format) ▼ notion-fable-proxy (127.0.0.1:8765) │ │ Agent cycle — requests to Notion AI ▼ Notion AI Models (fable-5 / gpt-5.6-sol) │ │ MCP calls tools ▼ notion-code-mcp (127.0.0.1:8787) list_files · read_file · write_file · edit_file · run_shell ``` 1. **`notion-fable-proxy`** — API proxy on port `8765`. Accepts requests in OpenAI format (for OpenCode, Codex CLI) or Anthropic Messages API (for Claude Code) and redirects them to Notion AI models, performing an agent cycle. 2. **`notion-code-mcp`** — local MCP server on port `8787`. Provides the agent with tools for working with the file system and executing shell commands. 3. **`notion-private-api-mcp`** — optional MCP for reading and editing Notion pages directly via `token_v2`. ### Project structure ``` notioncode_mcp/ ├── bridge/ # API proxy and agent cycle ├── runtime/ # Local MCP server (list_files, read_file, ...) ├── notion-private-api-mcp/ # MCP for Notion Private API (token_v2) ├── config/ # Configurations for OpenCode, Claude Code, VS Code, Codex CLI ├── browser/ # Launch Chrome + Xvfb + noVNC for Notion authorization ├── deploy/systemd/ # systemd units for automatic service startup ├── scripts/install-local.sh # Installer ├── bin/codex # Wrapper over Codex CLI with isolated CODEX_HOME └── requirements.txt # Python dependencies for bridge ``` The `.runtime/`, `state/`, `node_modules/`, and `runtime/.env` directories are not published. They store: Python venv, browser profile Notion, `token_v2`, session history, SQLite databases Codex CLI, local MCP secret. ## Requirements - Ubuntu server (tested on Ubuntu 22.04/24.04) - Python 3.10+ - Node.js 18+ - npm - `openssl` (for generating MCP secret) - Notion account with access to Fable 5 / GPT-5.6 Sol models - Installed OpenCode (`opencode`), Claude Code (`claude`), or Codex CLI — depending on the required client ## Installation ### 1. Clone the repository ```bash git clone <repo-url> /root/notioncode_mcp cd /root/notioncode_mcp ``` ### 2. Run the installer ```bash chmod +x scripts/install-local.sh sudo scripts/install-local.sh ``` The installer performs: - Creates Python venv in `.runtime/notion-agent-cli-venv` and installs dependencies from `requirements.txt` - Installs npm dependencies for `runtime/` and `notion-private-api-mcp/` - Generates `runtime/.env` with `MCP_PATH_SECRET` (random hex secret), `CODE_ROOT=/root`, `PORT=8787` - Creates symlinks: `.notionagents`, `notion-gui-profile`, venv, OpenCode, Claude Code, VS Code Remote configs - Installs and activates systemd units `notion-code-mcp` and `notion-fable-proxy` - Creates `/usr/local/bin/codex` → `bin/codex` ### 3. Authorize Notion After installation, you need to pass `token_v2` from your Notion account. **Method A — manually:** Copy `token_v2` from browser cookies (DevTools → Application → Cookies → `token_v2`) and write it to the account file in `state/notionagents/` according to the format expected by `notion-agent-cli`. **Method B — through browser (noVNC):** ```bash # Launch Chrome with noVNC for visual authorization bash browser/start.sh # Open in browser: http://<server-ip>:6080 # Log in to Notion, after which token_v2 will be saved automatically ``` ## Checking installation ```bash # Service status systemctl status notion-code-mcp notion-fable-proxy # API proxy check curl http://127.0.0.1:8765/healthz # Codex CLI check codex --version codex mcp list ``` ## Usage ### OpenCode ```bash cd /root/your-project opencode ``` Fable 5 is selected by default. For GPT-5.6 Sol: ```bash opencode run --model notion-fable/gpt-5.6-sol "Perform the task" ``` OpenCode accesses `http://127.0.0.1:8765` as an OpenAI-compatible API. Configuration is located in `config/opencode.jsonc`, symlink is installed in `~/.config/opencode/opencode.jsonc`. ### Claude Code (VS Code) 1. Install the `anthropic.claude-code` extension in VS Code. 2. Execute the command `Developer: Reload Window`. 3. The extension automatically uses `ANTHROPIC_BASE_URL=http://127.0.0.1:8765`, no Anthropic login is required. Fable 5 is selected by default. To change the model: - In the Claude Code chat, enter `/model` and select `GPT-5.6 Sol (Notion)` - Or run in the terminal: ```bash claude --model fable-5 claude --model gpt-5.6-sol ``` Default permission mode — `acceptEdits`: file editing is allowed without confirmation, potentially dangerous commands may require confirmation. Extension configuration: `config/claude-settings.json` → symlink `~/.claude/settings.json`. ### Codex CLI The `codex` terminal command is launched through `bin/codex` with isolated `CODEX_HOME` in `state/codex-cli/`. ```bash # Run with Fable 5 (by default) codex # Run with GPT-5.6 Sol codex -m gpt-5.6-sol # One-time task codex run "Perform the task" # List of connected MCP codex mcp list ``` In this profile, native `/goal` Codex is available and `notion-private` MCP is connected for working with Notion pages. > **Isolation:** Codex CLI in this profile is completely isolated from the VS Code extension (`openai.chatgpt`). The VS Code extension uses `/root/.codex` and original OpenAI models — the wrapper does not affect it. Configuration: `config/codex-cli-config.toml` → copied to `state/codex-cli/config.toml` during the first installation. ## System services Two systemd units are started automatically when the system starts: | Service | Description | Port | |---|---|---| | `notion-code-mcp` | Local MCP runtime (file system and shell tools) | `8787` | | `notion-fable-proxy` | Notion AI API proxy (OpenAI/Anthropic compatible) | `8765` | ```bash # Restart services systemctl restart notion-code-mcp notion-fable-proxy # View logs journalctl -u notion-fable-proxy -f journalctl -u notion-code-mcp -f ``` ## Model management The list of available models and their mapping is described in `config/codex-models.json`. Adding a new model: 1. Add a record to `config/codex-models.json`. 2. Restart `notion-fable-proxy`. ## How integration with Notion AI works The project uses **regular Notion AI** — not Custom Agent, but a standard AI chat available in any Notion workspace. Interaction occurs through a Python library that authorizes through (cookie of your session) and sends requests to the internal Notion AI API. ### How it works ### Operating modes **Planner mode** (used in OpenCode and Codex CLI without ): - The model is sent a special system prompt: it acts as a "coding planner" that does not perform actions itself but recommends exactly one action at a time in JSON format. - Example: - Bridge performs the action through MCP runtime, returns the result to the model in the same thread. - The cycle repeats until the model returns (maximum 20 steps). **Workflow mode** (used when specified ): - The model works as a native Notion agent with a workflow, it simulates tool calls in format. - Bridge intercepts such calls, performs them through MCP, and continues the thread (, ). **Streaming mode** (without tools, for example, in chat): - The model responds directly, text deltas are streamed to the client via SSE. ### Authentication and session - Authorization occurs through — cookie of your Notion browser session. - reads the account from (symlink to ). - is saved between steps of the cycle, so the model "remembers" the context of previous actions within one task. - Each new request from the client starts a new thread. ### Important limitations - **Unofficial internal Notion API** is used — it may change without warning. - and in planner mode are disabled so that the model focuses on local files. - Maximum cycle depth: 20 steps (planner mode) / 12 steps (workflow mode). ## Security Coding runtime listens only on `127.0.0.1`. Do not publish `runtime/.env`, `state/`, browser profile, and Notion cookie. Private Notion API is unofficial and may change without warning. ## Troubleshooting **Service does not start:** ```bash journalctl -u notion-fable-proxy --no-pager -n 50 ``` Ensure that the Python venv exists: `.runtime/notion-agent-cli-venv/bin/python`. **Notion authorization error:** Run the browser stream through `browser/start.sh` and re-authorize in Notion. **`codex` not found:** ```bash ls -la /usr/local/bin/codex # Should be a symlink to /root/notioncode_mcp/bin/codex sudo ln -sfn /root/notioncode_mcp/bin/codex /usr/local/bin/codex ``` **MCP does not connect:** ```bash curl http://127.0.0.1:8787/ # notion-code-mcp codex mcp list # Check the list of servers ``` --- ## Installation on Windows via OpenCode After registering at https://app.notion.com/ and subscribing, download `notioncode_mcp_v2.tar.gz` to a separate folder. If you don't have access to AI, install OpenCode: it has a free almost unlimited DeepSeek V4 Flash. Important: install via the command line, NOT via the VS Code extension. If you don't know how - ask any AI: "how to install opencode on Windows". Important for RF: everything works only via VPN. You can use `@sonnetvpn_bot` or https://sonnet.website/ ### Installing MCP Server 1. Open OpenCode in the command line. You can do this through cmd in the project folder, but it's more convenient through VS Code with the open folder where `notioncode_mcp_v2.tar.gz` is located. 2. Through `/models`, select DeepSeek V4 Flash Free. If it asks for thinking - Max. 3. Through `@`, select `notioncode_mcp_v2.tar.gz` and send: ```text @notioncode_mcp_v2.tar.gz unpack this archive in this folder ``` The archive will be unpacked in the current folder. 4. Send: ```text study this mcp server, detailed analysis, without it, do not change files. Understand the principle of work, it cannot be changed! This mcp is made for linux After a detailed analysis, adapt it exactly with the same principles of work under windows ``` Wait for completion. It should look like screenshot 4. 5. Install Codex CLI: ```text install codex cli. do not install mcp server yet ``` If OpenCode asks for permission - give all, Always Allow. 6. Check Codex CLI: in a separate terminal, type `codex` and Enter. The Codex interface should open with login options. Close it immediately through Ctrl+C or Ctrl+Z. If Codex was already installed and asks about trust in the folder/workspace - do not configure anything, just close it. 7. Return to OpenCode and send: ```text now install this mcp server, but do not connect to codex yet ``` Wait for installation. At the end, it should look like screenshot 7. 8. Send: ```text now study what data from the session (approx. token_v2) is necessary for the operation of this mcp server. After that, launch the browser page https://app.notion.com/ in which I will log in and then ask to remove cookies from it and throw it into the mcp server ``` OpenCode will open https://app.notion.com/ itself. Log in to the account with a subscription from the previous post. 9. After logging in, send: ```text i've logged in, remove necessary cookies and throw them into the mcp server. After that, connect codex to this mcp server constantly, not just for one session ``` Wait for completion. It should look like screenshot 8. If it writes "To work, you need to start services..." - send: ```text start yourself ``` 10. Launch Codex in a neighboring terminal with the command `codex`. You can do this together with the Codex extension in VS Code; with a separate application, I think it also works, but I haven't checked. If it asks for permission or asks about sandbox - give full access, not just from the administrator. If an error appears like: ```text ⚠ MCP client for `notion-private` failed to start: MCP startup failed: Syntax error in file name, directory name, or volume label. (os error 123) ⚠ MCP startup incomplete (failed: notion-private) ``` or similar - ignore it, it's "normal". After launching, write to Codex: `hello`. If the answer came - great. Then send: ```text create .py calculator in this folder ``` With successful setup, `calculator.py` will appear. 11. Done! Now you can use Codex in any project/folder. This is a full-fledged Codex, as if you had maximum subscriptions. OpenCode and extra windows can be closed - everything will continue to work. If you need to remove everything: open OpenCode, through `/sessions`, find the MCP server setup chat and send: ```text now delete this mcp server and its connection with codex ``` ### How to use - Models are changed through `/model` in Codex CLI or in the extension next to the send button; thinking is also adjusted there. - Several chats at once, especially through `/goal`, do not recommend: high probability of error 502. There are no limits, quotas, or restrictions - everything is completely unlimited. Enjoy using it! If you have questions - ask them in the comments.