Diagramify - automatic diagram creation for Notion

#notion #mcp #gemini #automation

I'm often writing descriptions and ideas on projects in Notion. And I thought: it'd be nice to have such system descriptions summarized in a diagram of proper kind, be it a flow diagram, decision diagram etc. And it'd be nice to have it done automagically.

So, I've built a simple Notion integration. It's made of 2 parts: a server, acting like a Notion MCP server, connecting to api.notion.com, and a client using this server. That way I could omit using a full-blown official Notion MCP server, requiring full OAuth authorization, playing with tokens etc. It's just a simple tool running on my own local machine, connecting directly to API.

How it works?

The server part is mimicking what official MCP server is doing, but it's adapted to my needs, like if it gets a page, which is long, it gets care of getting all the parts, etc. That way the client itself is much easier to write and maintain.
Both server and client are written in Python. All you need to do is to create an internal integration on Notion Integrations page. From there, take your Notion token and put it in .env file:

NOTION_TOKEN = "YOUR_NOTION_TOKEN"

Server

Server is using Starlette and MCP modules as its main core, using SSE Transport. And yes, it should be updated to use HTTP Stream Transport instead, but I've left that for some day.
Now, the server has a number of tools the client can use. My list of tools is different from the original Notion MCP server, as it's suited for my task. For this simple integration it's:

list_accessible_pages: gets all the pages that were connected to our integration in Notion UI;
get_notion_object: gets the object and its info. If it's a big object, get all the blocks.
upsert_mermaid_block: inserts or updates the Mermaid block.

Client

Now, how it's working?
As the core functionality is automagic diagram insertion, I'm just using Gemini 2.5 Flash AI model to generate the diagram, feeding it with the whole text of the page.
Inserted diagram is timestamped, so the client can know if the page was updated afterwards and needs refreshing of the diagram.

The exact flow of the client is:

get the list pages it has access to;
download whole page;
search for a signature with a timestamp;
if the signature doesn't exist, or the timestamp is older than the update date of the page: insert or update the mermaid block, the code itself comes from Gemini.

Simple as that.

There's also one thing to consider, while creating Mermaid diagrams with Gemini: while it's really good at it, it can sometimes do syntax errors, especially in complicated diagrams. That's why my prompt lists few rules.

Another thing is a hard limit of a single block length in Notion. It's only 2000 characters. It sounds as enough, but for large complicated diagrams it can be too small. Hence my prompt says exactly that and adds "if it's too long, simplify the diagram and omit less important elements".

Automating the run

I'm using Windows. For such tasks I like using the PM2. All it needs is creating a simple config file:

module.exports = {
    apps : [
    {
        name: "notion-server",
        script: "notion_server.py",
        interpreter: "./PythonEnv/python.exe",
        autorestart: true,
        watch: false,
        env: {
            NODE_ENV: "production",
            PYTHONIOENCODING: "utf-8",
            PYTHONUTF8: "1"
        }
    },
    {
        name: "notion-worker",
        script: "notion_client_local.py",
        interpreter: "./PythonEnv/python.exe",
        autorestart: true,
        restart_delay: 300000,
        watch: false,
        env: {
            NODE_ENV: "production",
            PYTHONIOENCODING: "utf-8",
            PYTHONUTF8: "1"
        }
    }
  ]
}

With this config, it will take care of running the server and running the client every 5 minutes.

The sources

All the sources are available on GitHub, just keep in mind it's in Polish (both comments and Gemini's prompt), but I think you can easily get the grasp of what it's doing. The code is really simple.

DEV Community