buildin-mcp

# buildin-mcp An MCP (Model Context Protocol) server for [Buildin.ai](https://buildin.ai) — gives LLMs (Claude Desktop, Claude Code, Cursor, etc.) full access to pages, databases, blocks, search, users, and Markdown helpers. 19 tools total. ## Getting your API token 1. Go to [Buildin.ai Integrations](https://buildin.ai/dev/integrations/internal/create) 2. Create a new **Plugin** 3. In the permissions section, enable: - **Read data** - **Write data** - **Edit data** 4. Copy the generated token (starts with `sk-...`) ## Quick start ```bash BUILDIN_API_TOKEN=sk-... npx buildin-mcp ``` The server starts on stdio and is ready to accept MCP requests. ## Usage with MCP clients ### Claude Desktop Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "buildin": { "command": "npx", "args": ["-y", "buildin-mcp"], "env": { "BUILDIN_API_TOKEN": "sk-..." } } } } ``` ### Claude Code ```bash claude mcp add buildin -e BUILDIN_API_TOKEN=sk-... -- npx -y buildin-mcp ``` ### Cursor Add to `.cursor/mcp.json`: ```json { "mcpServers": { "buildin": { "command": "npx", "args": ["-y", "buildin-mcp"], "env": { "BUILDIN_API_TOKEN": "sk-..." } } } } ``` ### Windsurf / any stdio MCP client ```bash BUILDIN_API_TOKEN=sk-... npx -y buildin-mcp ``` ### OpenCode Add to your project's `opencode.jsonc` or global `~/.config/opencode/opencode.jsonc` (inside the `"mcp"` section): ```jsonc "buildin": { "type": "local", "command": ["npx", "-y", "buildin-mcp"], "environment": { "BUILDIN_API_TOKEN": "sk-..." }, "enabled": true } ``` > **Note:** OpenCode uses `"environment"` (not `"env"`) for passing environment variables to local MCP servers. ## Install from source (optional) ```bash git clone https://github.com/ekho/buildin-mcp.git cd buildin-mcp npm install npm run build node dist/index.js ``` ## Environment variables | Variable | Required | Description | |---|---|---| | `BUILDIN_API_TOKEN` | **yes** | Plugin token from Buildin.ai | | `BUILDIN_API_BASE_URL` | no | Override API base (default: `https://api.buildin.ai/v1`) | | `BUILDIN_MCP_DEBUG` | no | Set to `1` for verbose debug logging to stderr | --- ## Tools (19 total) ### Pages (5) - `buildin_create_page` — POST /v1/pages - `buildin_get_page` — GET /v1/pages/{id} - `buildin_update_page` — PATCH /v1/pages/{id} - `buildin_archive_page` — PATCH /v1/pages/{id} with `archived=true` - `buildin_get_page_children` — GET /v1/blocks/{page_id}/children ### Databases (4) - `buildin_create_database` — POST /v1/databases - `buildin_get_database` — GET /v1/databases/{id} - `buildin_query_database` — POST /v1/databases/{id}/query - `buildin_update_database` — PATCH /v1/databases/{id} ### Blocks (5) - `buildin_get_block` — GET /v1/blocks/{id} - `buildin_get_block_children` — GET /v1/blocks/{id}/children - `buildin_append_block_children` — PATCH /v1/blocks/{id}/children - `buildin_update_block` — PATCH /v1/blocks/{id} - `buildin_delete_block` — DELETE /v1/blocks/{id} ### Search & Users (2) - `buildin_search` — POST /v1/search - `buildin_get_me` — GET /v1/users/me ### Markdown helpers (3) - `buildin_append_markdown` — convert Markdown to Buildin blocks and append - `buildin_get_page_markdown` — read a page's contents as Markdown - `buildin_search_and_fetch` — search + auto-fetch contents of the top N pages > Buildin.ai does not expose a Comments API or a hard-delete for pages — archive is the documented way to remove pages. ## Development - **Runtime:** Node 18+, TypeScript 5.6, ESM. - **Transport:** stdio only. - **Logging:** stderr only — stdout is reserved for MCP JSON-RPC. Never `console.log`. - **Retries:** automatic on 429 and 5xx (except 501), exponential backoff, 3 attempts. ### Verify ```bash npm run typecheck # tsc --noEmit npm run build # compiles to dist/ npm test # unit tests for markdown converters npm run smoke # stdio JSON-RPC: initialize + tools/list must return 19 tools ``` ## License MIT