home / mcp / writer mcp

Writer MCP

MCP server for writer

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "huangjien-writer-mcp": {
      "command": "python",
      "args": [
        "run_server.py"
      ],
      "env": {
        "APP_NAME": "Writer MCP",
        "CHAT_MODEL": "gpt-4o-mini",
        "DEBUG_MODE": "true",
        "DATABASE_URL": "postgresql://username:password@localhost:5432/writer_mcp",
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY",
        "EMBEDDING_MODEL": "text-embedding-3-small",
        "MCP_SERVER_NAME": "writer-mcp",
        "OPENAI_BASE_URL": "https://api.openai.com/v1",
        "MAX_SEARCH_LIMIT": "100",
        "VECTOR_DIMENSION": "1536",
        "TEST_DATABASE_URL": "postgresql://username:password@localhost:5432/writer_mcp_test",
        "MCP_SERVER_VERSION": "1.0.0",
        "DEFAULT_SEARCH_LIMIT": "10"
      }
    }
  }
}

Writer MCP is a server for managing character knowledge and relationships in creative writing projects. It stores character data, factual knowledge, and relationships, and uses AI-powered tagging and semantic search to help you build consistent worlds and rich character dynamics.

How to use

You interact with Writer MCP through a client or tooling layer that speaks the MCP protocol. You can create characters with rich descriptions, add knowledge facts, link facts to characters, and analyze how characters relate to one another. Use the search features to retrieve characters or facts by content or semantic meaning, and rely on generated tags to categorize characters and relationships for quick discovery.

How to install

Prerequisites: Python 3.8+ and a working PostgreSQL server.

# Clone the project
git clone <repository-url>
cd writer-mcp

# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .

Configuration notes

Set up environment variables to configure the database, AI services, and server metadata. Create a copy of the example env file and edit the values as needed.

# Copy example config
cp .env.example .env

# Edit .env with your database and API credentials:
DATABASE_URL=postgresql://username:password@localhost:5432/writer_mcp
TEST_DATABASE_URL=postgresql://username:password@localhost:5432/writer_mcp_test

OPENAI_API_KEY=your_openai_api_key_here
OPENAI_BASE_URL=https://api.openai.com/v1
CHAT_MODEL=gpt-4o-mini
EMBEDDING_MODEL=text-embedding-3-small

APP_NAME=Writer MCP
DEBUG_MODE=true

VECTOR_DIMENSION=1536

DEFAULT_SEARCH_LIMIT=10
MAX_SEARCH_LIMIT=100

MCP_SERVER_NAME=writer-mcp
MCP_SERVER_VERSION=1.0.0

Initializing and starting the server

Initialize the database (first run) and start the MCP server.

python scripts/init_db.py

python run_server.py

Project structure highlights

Key parts you’ll interact with include the configuration management, server entry point, database layer, data models, business logic, tools, and supporting utilities.

Security and maintenance notes

Keep your OpenAI API key secure. Use strong, rotation-friendly credentials for your PostgreSQL instance. Regularly review access controls and rotate keys as needed.

Available tools

create_character

Create a new character with rich descriptions and metadata.

search_characters

Search for characters by name, description, or metadata using textual or semantic queries.

add_character_fact

Attach a factual statement to a character, enabling knowledge collection.

search_facts

Search through stored character facts with textual or semantic queries.

generate_character_tags

Generate AI-powered tags to categorize characters and their traits.

analyze_character_relationships

Analyze and summarize relationships between characters based on stored facts and interactions.