home / mcp / music and madness sync bridge mcp server

Music and Madness Sync Bridge MCP Server

Bridges Foundry journals to Notion with mirror blocks, media copies, and conflict-aware synchronization.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "captaincurso-music-madness-sync-bridge": {
      "command": "npm",
      "args": [
        "run",
        "mcp:start"
      ],
      "env": {
        "FOUNDRY_BASE_URL": "<FOUNDRY_BASE_URL>",
        "NOTION_STORY_BIBLE_PAGE_ID": "<NOTION_STORY_BIBLE_PAGE_ID>",
        "NOTION_ALLOWED_DATABASE_IDS": "<NOTION_ALLOWED_DATABASE_IDS>",
        "NOTION_DEFAULT_TARGET_DB_ID": "<NOTION_DEFAULT_TARGET_DB_ID>"
      }
    }
  }
}

You can run a local MCP server that exposes bridge tools for orchestrating synchronization between Foundry and Notion, enabling controlled, manual, or automated workflows with mirror blocks, journal organization, and media handling. This server focuses on safe, non-destructive writes, conflict tracking, and a dedicated Journals wiki tree to mirror Foundry content into Notion.

How to use

You operate the MCP server from your development environment using standard npm-based commands. Start by running the MCP server, then interact with the exposed tools to preview, apply, or inspect changes between Foundry and Notion. Use the available health and conflict utilities to ensure integrity before performing updates.

How to install

Prerequisites: you need Node.js and npm installed on your system. You also need access to a Notion workspace and a Foundry instance configured for bridging.

# 1. Clone the project repository
# (Replace with your actual clone URL if you have one)
git clone https://github.com/captaincurso/music-madness-sync-bridge.git
cd music-madness-sync-bridge

# 2. Install dependencies
npm install

# 3. Copy and configure environment variables
cp .env.example .env
```} ,{

4. Populate the environment values in .env according to your Foundry, Notion, and Story Bible setup. Typical values include Foundry site information, Notion API keys, and the Notion page IDs.

# 5. Typecheck the TypeScript sources
npm run typecheck

# 6. Start the MCP server (stdio) for interactive usage
npm run mcp:start

Additional sections

Configuration and security notes: the server enforces guardrails so you only write to Notion pages within the approved database IDs and preserves existing prose by appending or updating the generated mirror block. The legacy Music and Madness section remains untouched unless explicitly targeted by the allowed databases.

Usage patterns and workflow tips: preview changes before applying to see the potential updates without writing. Use the conflicts tooling to inspect, resolve, and annotate manual merges when necessary. Media handling is enabled by default but can be disabled per operation to control bandwidth and storage.

If Foundry is not ready or you want a mock API for local testing, you can enable a mock Foundry API to simulate endpoints like health and journals. This is helpful when your Foundry module routes are not fully live.

Available tools

sync.foundry_to_notion.preview

Preview mirror updates between Foundry and Notion without writing to Notion pages. Shows what would change in the Journals tree.

foundry.health_check

Check the health of the Foundry integration and readiness for synchronization.

foundry.list_journals

List available Foundry journals to inspect what can be synced.

foundry.get_journal

Retrieve a specific Foundry journal and its contents for synchronization.

foundry.export_journal_media

Export or link journal media to the local durable storage and Notion.

sync.foundry_to_notion.apply

Apply mirror updates from Foundry to Notion, creating or updating pages under Journals and syncing media as configured.

sync.diff

Show differences between source Foundry data and target Notion data to aid review.

sync.conflicts.list

List conflicts detected since the last sync, enabling manual resolution.

sync.conflicts.resolve

Resolve a specific conflict with a given strategy and optional notes.