notion-mcp-server

Automatically converts Notion's OpenAPI specification (notion-openapi.json) into MCP-compliant tool definitions at server startup, eliminating manual tool definition maintenance. The system parses the OpenAPI schema, extracts operation metadata (parameters, request/response types), and generates tool schemas that MCP clients can discover via the listTools protocol method. This approach ensures the entire Notion API surface is immediately available without hardcoding individual operations.

Implements the MCPProxy class that translates between MCP's standardized tool interface (listTools for discovery, callTool for execution) and Notion's REST API operations. The proxy intercepts MCP requests, maps tool invocations to OpenAPI operation definitions, constructs HTTP requests with proper parameter binding, and marshals responses back into MCP-compatible formats. This abstraction decouples the MCP protocol from underlying API implementation details.

Provides two deployment mechanisms: Docker containerization (Dockerfile with Node.js runtime) and NPM package distribution (published to npm registry). The Docker deployment bundles the server with all dependencies and environment variable configuration, while NPM deployment allows installation via `npm install` or `npx` for local development and testing. Both deployment methods expose the same CLI interface and support identical configuration through environment variables and command-line arguments.

Respects Notion API permission model by executing operations only with the scope granted to the authentication token. The server does not implement additional authorization logic — all permission enforcement is delegated to Notion API, which returns 403 Forbidden for operations outside the token's scope. This design ensures the server cannot grant broader access than the token allows and maintains security boundaries defined by Notion workspace administrators.

Provides two independent transport mechanisms for MCP communication: STDIO for desktop AI clients (Claude Desktop, Cursor, Zed) and HTTP for web-based applications. The server initializes the appropriate transport based on CLI arguments, using MCP SDK's transport abstractions to handle protocol framing, message serialization, and connection lifecycle. Both transports implement the same MCP server interface, allowing identical tool definitions and behavior across deployment contexts.

Implements an HttpClient that constructs and executes HTTP requests to the Notion API with automatic authentication header injection (NOTION_API_KEY from environment). Each tool invocation triggers a new HTTP request with parameters bound from MCP tool arguments, request/response bodies serialized as JSON, and proper Content-Type headers. The client handles URL construction from OpenAPI operation definitions, parameter placement (query, path, body), and response parsing without maintaining connection state or request history.

Transforms OpenAPI operation definitions into MCP-compatible tool schemas by mapping OpenAPI parameters (query, path, body) to MCP's inputSchema format (JSON Schema). The conversion extracts operation metadata (operationId, summary, description), builds parameter schemas with proper type constraints and required field markers, and generates human-readable tool descriptions. This conversion happens at server startup and caches the result in the tool registry for discovery requests.

Provides a CLI entry point (bin/cli.mjs) that parses command-line arguments to configure server behavior: transport type (stdio or http), port (for HTTP), and authentication token. The startup process loads the OpenAPI specification, initializes MCPProxy with converted tool definitions, creates the appropriate transport, and starts the MCP server. This initialization is synchronous and happens once per server lifetime, with all configuration derived from CLI arguments and environment variables.

Maps MCP tool invocation arguments to Notion API request parameters by matching argument names to OpenAPI parameter definitions and placing them in the correct location (query string, URL path, request body). The binding process validates that required parameters are present, coerces types according to OpenAPI schema, and constructs the final HTTP request. This happens for every tool invocation and ensures parameter values from MCP clients reach the Notion API in the correct format.

Converts Notion API HTTP responses (JSON bodies, status codes, headers) into MCP-compatible result objects that clients can consume. The marshaling process parses JSON response bodies, extracts relevant data fields, handles error responses by mapping HTTP status codes to MCP error formats, and structures the result according to MCP callTool response schema. This happens synchronously after each HTTP request and ensures API responses are presented consistently to MCP clients.

Maintains an in-memory registry of MCP tools generated from OpenAPI operations, populated once at server startup and served to clients via the listTools protocol method. The registry is indexed by tool name (derived from operationId) and contains complete tool schemas (name, description, inputSchema). This caching approach eliminates repeated OpenAPI parsing and schema conversion, making tool discovery fast and consistent across client requests.

Manages Notion API authentication through the NOTION_API_KEY environment variable, injected into every HTTP request as an Authorization header. The token is loaded once at server startup and reused for all subsequent API calls without refresh logic. This approach is stateless and portable across deployment contexts (Docker, NPM, local development) but requires the token to remain valid for the entire server lifetime.