@btm-ai/notion-query-mcp

An MCP server that gives AI agents filtered, paginated query access to Notion databases — the database query and schema capability the hosted Notion MCP (mcp.notion.com) does not provide. It runs alongside the hosted MCP, not as a replacement.

Tools

| Tool | Purpose | |---|---| | notion_query_database | Query a database with optional Notion filter/sorts; auto-paginates and returns each page flattened to id, url, and its properties (up to page_size, max 200). | | notion_query_database_schema | Return a database's title and every property's name/type, including select/multi_select option names. | | notion_get_page | Fetch a single page by ID and return its id, url, and full property values. |

Requirements

• Node.js 24 LTS or newer.
• A Notion internal integration token.

Environment variables

| Name | Required | Description | |---|---|---| | NOTION_TOKEN | Yes | Notion internal integration token used for all outbound Notion API calls. Never commit this; set it as an environment variable / platform secret. | | PORT | No | HTTP listen port for the Streamable HTTP transport (defaults to 3000 locally; injected by the platform in production). |

Connecting from Claude.ai

The production server exposes the MCP Streamable HTTP transport. Add it as a custom MCP connector using the deployed HTTPS endpoint:

https://<your-railway-service>.up.railway.app/mcp

A health check is available at GET /healthz.

Running locally (stdio)

For local clients such as Claude Desktop or Claude Code, run the stdio entrypoint via npx:

NOTION_TOKEN=secret_xxx npx @btm-ai/notion-query-mcp@latest

Use the @latest tag to avoid running a stale npx-cached version.

Or from a checkout of this repo:

npm install
cp .env.example .env   # then set NOTION_TOKEN
npm run dev:stdio      # stdio transport
npm run dev:http       # Streamable HTTP on http://localhost:3000

Distribution

Published to npm for npx support (see package.json bin). Install with npx @btm-ai/notion-query-mcp@latest.

TODO: MCPB packaging — post-MVP — bundling as an .mcpb package (@anthropic-ai/mcpb + manifest.json with tool descriptions, auth fields, and icon assets) for the Anthropic curated MCP directory is deferred until those assets exist.