BluePeriod MCP Integration Guide

This document explains how to connect external AI agents (like Claude Code, Cursor, or your own MCP-enabled tools) to the BluePeriod desktop application.

🔗 Overview

BluePeriod implements the Model Context Protocol (MCP). This allows external, powerful AI agents to "reach inside" the app to read your plot, analyze your manuscript, and apply high-quality edits.

🚀 Setup Instructions

Currently, the MCP connection is established via a stdio proxy that communicates with the local BluePeriod development server.

1. Start BluePeriod

Ensure the core application is running in development mode. We use a custom port 3703 to avoid common conflicts:

# In next-app directory
bun run dev --port 3703

The app must be open and active for tools to execute, as the bridge logic runs within the WebView.

2. Configure Your MCP Client

To use BluePeriod with an external tool (e.g., Claude Code), add the following server configuration to your MCP config file (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "blueperiod": {
      "command": "bun",
      "args": [
        "run",
        "e:/Creative/Program/MyProgram/BluePeriod/dev/blueperiod/next-app/scripts/mcp-stdio-server.ts"
      ],
      "env": {
        "BLUEPERIOD_API_URL": "http://localhost:3703/api/mcp"
      }
    }
  }
}

(Note: Use the absolute path to the script on your system.)

📦 Production (Installed App) Note

When using the built .exe or .app version of BluePeriod:

• The mcp-stdio-server will be bundled as a Sidecar binary.
• You won't need bun or the source code to connect.
• Detailed production setup instructions will be provided in the release notes of the bundled installer.

🛡 Security and Port Management

• Default Port: We use 3703 to avoid conflicts with other development projects (usually on 3000, 5173, etc.).
• Manual Override: If you need to change the port, update both the bun run dev command and the BLUEPERIOD_API_URL env var in your MCP config. Usage inside Claude Code Once configured and started, you can ask Claude:
• "Show me the BluePeriod project list."
• "Get the latest plot structure and analyze its contents."
• "Revise the manuscript for Chapter 1, Section 2 using Adit to make it more tense."

🛡 Security Note

Currently, the MCP bridge is designed for local use. It listens on localhost:3703 by default. Ensure you are running in a trusted network environment. Future updates will include authentication tokens for enhanced security.

📚 Related Documentation

• mcp_blueperiod_writing_skill - Guide for AI agents on how to use the tools.
• 2026-03-09_1205_plan_mcp_integration_desktop - Technical implementation plan.