CivNode MCP Server

MCP server for CivNode — the AI-powered creative writing platform where every human gets exactly one page (a Monument) displayed at random. No algorithm, no likes, no followers.

263 tools for writing, world-building (characters, locations, creatures, plots, family trees), entity exploration, books, collections, showcase, research, marketplace, library, forums, competitions, collaboration, passage comments, civic room, file management, and platform administration.

Quick Start

npx @civnode/mcp

No installation required. The server runs via npx and communicates over stdio using the Model Context Protocol.

Configuration

Claude Desktop

Add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "civnode": {
      "command": "npx",
      "args": ["-y", "@civnode/mcp"],
      "env": {
        "CIVNODE_SESSION_TOKEN": "your-session-token"
      }
    }
  }
}

Claude Code

Add to .claude/settings.json or ~/.claude/settings.json:

{
  "mcpServers": {
    "civnode": {
      "command": "npx",
      "args": ["-y", "@civnode/mcp"],
      "env": {
        "CIVNODE_SESSION_TOKEN": "your-session-token"
      }
    }
  }
}

Environment Variables

Variable	Required	Description
CIVNODE_SESSION_TOKEN	For authenticated tools	Your CivNode session token
CIVNODE_API_URL	No	API base URL (default: https://civnode.com)

Authentication

Tools fall into three categories:

• Public — No token needed. Browse monuments, read works, search users.
• Authenticated — Requires CIVNODE_SESSION_TOKEN. Publishing, messaging, managing your compendium.
• Admin — Requires a token with admin role. System management, moderation, bot simulation. These tools only appear when a token is configured.

To get a session token, log in to CivNode and go to Settings → API Token.

---

Tool Reference

Monuments

Every user has exactly one Monument — their single page on the platform, displayed at random to visitors.

Tool	Auth	Description
get_random_monument	No	Get a random Monument. Optionally filter by mood tags.
get_monument	No	Read a specific Monument by UUID.
get_monument_by_alias	No	Read a user's Monument by their alias.
publish_monument	Yes	Publish or update your Monument. Accepts title, body (Markdown), sources, identity mode.
resonate	Yes	Leave quiet appreciation on a Monument or work (CivNode's alternative to likes).
user_update_working_on	Yes	Set or clear the "currently working on" status shown on your profile (max 100 chars, optional work link).

Letters

Anonymous letters sent to Monument authors, plus direct personal letters between users.

Tool	Auth	Description
send_letter	Yes	Send an anonymous letter to a Monument author (max 500 words).
get_public_letters	No	Get publicly displayed letters on a user's Monument.
personal_letter_inbox	Yes	Get your personal letter inbox.
personal_letter_sent	Yes	Get your sent personal letters.
send_personal_letter	Yes	Send a direct, non-anonymous letter to another user.
read_personal_letter	Yes	Read a specific personal letter (marks as read).

Writing

Create, publish, and manage creative writing — poems, short stories, essays, novellas, and more.

Tool	Auth	Description
browse_writing	No	Browse published works. Filter by literary form or mood.
get_work	No	Read a specific work by UUID.
search_writing	No	Full-text search across published works.
publish_work	Yes	Publish a new work with title, content (Markdown), form, mood tags, and visibility.
list_my_works	Yes	List your own works (drafts and published).
update_work	Yes	Update a work's content, title, mood tags, or visibility.
delete_work	Yes	Delete a work permanently.
export_work	Yes	Export a work's content.
get_series	No	Get a writing series with all its works in reading order.
create_series	Yes	Create a new writing series.
list_my_series	Yes	List your writing series.
add_work_to_series	Yes	Add a work to a series.

Characters

Full character management with AI generation, portraits, and marketplace publishing.

Tool	Auth	Description
list_characters	Yes	List your characters.
get_character	Yes	Get a character's full profile.
create_character	Yes	Create a character (only name required, fill rest later or use AI).
update_character	Yes	Update character fields (pass only fields to change).
delete_character	Yes	Delete a character permanently.
ai_generate_character	Yes	Generate a complete character using AI. Accepts role, genre, setting hints.
character_portrait_generate	Yes	Generate an AI portrait. Requires an image provider.
character_suggestions	Yes	Get AI suggestions for a specific field (appearance, personality, backstory, etc.).
character_publish	Yes	Publish to the marketplace.
character_unpublish	Yes	Remove from the marketplace.
character_relationships	Yes	Get all relationships for a character.
entity_explorer_chat_character	Yes	Interview a character via the Entity Explorer. Chat in character, grounded in your story data. Requires BYOK AI provider.

Locations

World-building locations with areas, blueprints, and AI-powered generation.

Tool	Auth	Description
list_locations	Yes	List your locations.
get_location	Yes	Get full location details.
create_location	Yes	Create a location (name required). Fields: description, atmosphere, sensory details, inhabitants, secrets, etc.
update_location	Yes	Update location fields.
delete_location	Yes	Delete a location permanently.
location_ai_fill	Yes	AI fills in missing details based on name and existing fields.
location_ai_image	Yes	Generate an AI image. Requires an image provider.
location_publish	Yes	Publish to the marketplace.
location_unpublish	Yes	Remove from the marketplace.
get_location_blueprint	Yes	Get the visual blueprint/map.
entity_explorer_chat_location	Yes	Explore a location via the Entity Explorer. Analyze ripple effects of changes. Requires BYOK AI provider.

Creatures

Creatures and fantastical beings with full AI support.

Tool	Auth	Description
list_creatures	Yes	List your creatures.
get_creature	Yes	Get full creature profile.
create_creature	Yes	Create a creature (name and species_type required).
update_creature	Yes	Update creature fields.
delete_creature	Yes	Delete a creature permanently.
ai_generate_creature	Yes	Generate a creature using AI. Accepts species_type, habitat_type, era.
creature_ai_image	Yes	Generate an AI image.
creature_portrait_generate	Yes	Generate an AI portrait.
creature_publish	Yes	Publish to the marketplace.
creature_unpublish	Yes	Remove from the marketplace.
creature_suggestions	Yes	Get AI suggestions for a field.
entity_explorer_chat_creature	Yes	Interview a creature via the Entity Explorer. Chat in character, grounded in your story data. Requires BYOK AI provider.

Plots

Structured plot outlines with acts, scenes, beats, and AI generation.

Tool	Auth	Description
list_plots	Yes	List your plots.
get_plot	Yes	Get full plot with acts, scenes, and beats.
create_plot	Yes	Create a plot (title required). Fields: genre, tone, central_conflict, etc.
update_plot	Yes	Update plot fields.
delete_plot	Yes	Delete a plot permanently.
plot_add_act	Yes	Add an act (title, summary, purpose, notes).
plot_ai_acts	Yes	Generate acts using AI.
plot_add_scene	Yes	Add a scene to an act.
update_plot_scene	Yes	Update a scene's text fields (title, summary, purpose, style_hint, pov_character, notes), location bindings (region_id, area_id, spot_id — pass null to clear), or move it between acts in the same plot by passing act_id (optionally with sort_order to position it in the new act).
plot_ai_scenes	Yes	Generate scenes for an act using AI.
plot_ai_image	Yes	Generate an AI image for the plot.
plot_publish	Yes	Publish to the marketplace.
plot_unpublish	Yes	Remove from the marketplace.
entity_explorer_chat_plot	Yes	Explore a plot via the Entity Explorer. Analyze branching possibilities and tension points. Requires BYOK AI provider.

Plot Designer (Book-level)

Tools for the dedicated Plot Designer screen at /books/{bookId}/plot.

Tool	Auth	Description
list_plot_templates	No	List available plot structure templates (Three-Act, Hero's Journey, etc.).
get_plot_template	Yes	Get a single plot template with full beat details (acts → beats → name + hint).
get_book_plot	Yes	Get the plot linked to a book with all acts, scenes, and beats.
create_book_plot_from_template	Yes	Create a plot from a template and link to a book.
get_plot_synopsis	Yes	Read the cached AI synopsis for a book's plot. Does not trigger regeneration. Returns {synopsis, hash, generated_at} or null fields if none has been generated.
regenerate_plot_synopsis	Yes	Force regeneration of the AI synopsis. Cache-aware: returns the cached value if the plot content hasn't drifted. Requires BYOK.
delete_book_plot	Yes	Delete the plot linked to a book.
create_plot_beat	Yes	Create a beat under a scene. sort_order auto-assigned.
update_plot_beat	Yes	Update fields on a plot beat. Pass only the fields to change.
delete_plot_beat	Yes	Delete a plot beat by UUID.
reorder_plot_beats	Yes	Reorder beats within a scene via {id, sort_order} list.
get_beat_suggestions	Yes	Get story evidence suggestions for a beat (analysis, text stats, semantic).
auto_map_plot	Yes	Batch-map story content to all empty beats using analysis + AI.

Family Trees

Visual family trees linking characters and creatures with relationship tracking.

Tool	Auth	Description
list_trees	Yes	List your family trees.
get_tree_members	Yes	Get all members in a tree.
create_tree	Yes	Create a family tree (name required).
update_tree	Yes	Update tree name or description.
delete_tree	Yes	Delete a tree permanently.
tree_add_member	Yes	Add a character or creature to a tree.
tree_generate	Yes	Generate family members using AI.
tree_publish	Yes	Publish to the marketplace.
tree_unpublish	Yes	Remove from the marketplace.

Books

Full book management — create books with chapters, link compendium entities, export.

Tool	Auth	Description
list_books	Yes	List your books.
list_my_stories	Yes	List the user's books that have a plot. Subset of list_books. Useful for "what stories am I working on?"
search_my_stories	Yes	Full-text search over your Stories including character names. Returns books ranked by relevance.
get_book	Yes	Get book details and linked entities.
create_book	Yes	Create a book (title and book_type required). Types: novel, poetry_collection, essay_collection, screenplay. For screenplays, also pass screenplay_format.
update_book	Yes	Update book metadata (title, subtitle, blurb, genre, etc.). Set published: true/false to publish or unpublish a book to the marketplace. Screenplays support screenplay_format, screenplay_font, screenplay_title_page.
delete_book	Yes	Delete a book and all chapters.
list_chapters	Yes	List chapters in a book.
get_chapter	Yes	Get a chapter's content and metadata.
create_chapter	Yes	Create a chapter (title and chapter_type required). Types: chapter, prologue, epilogue, interlude, appendix. Optional plot_scene_id links the new chapter to a plot scene you own (silently skipped if the scene isn't on one of your plots) — powers the Plot Canvas drawer's "Create chapter from this scene" button.
update_chapter	Yes	Update chapter content or metadata.
delete_chapter	Yes	Delete a chapter.
reorder_chapters	Yes	Reorder chapters (pass chapter IDs in desired order).
book_link_entity	Yes	Link a compendium entity to a book (characters, creatures, locations, plots, trees).
book_unlink_entity	Yes	Remove a linked entity from a book.
export_book	Yes	Export a book's content in various formats (json, markdown, html, epub, pdf, fdx, fountain).
import_fountain	Yes	Import a Fountain screenplay as a new book.
book_entities	Yes	Get all entity types linked to a book in one call (characters, creatures, locations, plots, trees).
compendium_unassigned	Yes	Get entities not linked to any book or work.
get_public_book	No	Get a published book's public info.

Collections

Group books and works into ordered collections.

Tool	Auth	Description
create_collection	Yes	Create a new collection (title required, optional description).
list_collections	Yes	List all your collections.
get_collection	Yes	Get a collection with its ordered items (books and works).
update_collection	Yes	Update a collection's title or description.
delete_collection	Yes	Delete a collection (items are unlinked, not deleted).
collection_add_item	Yes	Add a book or work to a collection.
collection_remove_item	Yes	Remove an item from a collection.
collection_reorder	Yes	Reorder items in a collection by passing ordered item IDs.

Showcase

Your showcase is your public gallery — the books, works, and collections you have chosen to share with visitors.

Tool	Auth	Description
showcase_list	No	Get a user's public showcase items. Supports search, type filtering, and pagination.
showcase_count	No	Get the number of items in a user's showcase.
showcase_add	Yes	Add a book, work, or collection to your showcase. Provide exactly one ID.
showcase_mine	Yes	List your own showcase items.
showcase_update_note	Yes	Update the author note on a showcase item (max 280 chars).
showcase_remove	Yes	Retract an item from your showcase. It stays in My Writing but becomes private.
showcase_reorder	Yes	Set display order by providing item IDs in the desired order.

Canvases

Collaborative drawing and brainstorming boards within groups.

Tool	Auth	Description
list_canvases	Yes	List your canvases.
get_canvas	Yes	Get a canvas with nodes and metadata.
create_canvas	Yes	Create a canvas in a group.
update_canvas	Yes	Update canvas name.
delete_canvas	Yes	Delete a canvas permanently.

Passage Comments

Contextual feedback anchored to specific text passages in works and monuments.

Tool	Auth	Description
passage_comments_inbox	Yes	Get passage comments others left on your works.
passage_comments_mine	Yes	Get passage comments you wrote on other works.
passage_comments_create	Yes	Create a passage comment anchored to a text selection.
passage_comments_list	Yes	List passage comments for a specific work or monument.
passage_comments_reply	Yes	Reply to a passage comment.
passage_comments_delete	Yes	Delete a passage comment.
passage_comments_resonate	Yes	Leave quiet appreciation on a passage comment.
passage_comments_escalate	Yes	Escalate a passage comment for moderation review.
passage_comments_mark_read	Yes	Mark a passage comment as read.
passage_comments_dismiss	Yes	Dismiss a passage comment from your inbox.

Research & Observatory

Semantic search, tiered chapter analysis, writing insights, and AI-powered questions about your work.

Tool	Auth	Description
research_search	Yes	Semantic search across research notes and analyzed content.
research_analyze_chapter	Yes	Trigger tiered chapter analysis. Core (Tier 1): characters, themes, arcs, interactions. Deep (Tier 2): voice, foreshadowing, craft metrics. Requires AI provider.
research_intelligence	Yes	Get aggregated intelligence: character appearances, themes, timeline.
research_character_graph	Yes	Get a character's relationship graph and arc.
observatory_insights	Yes	Get writing insights and patterns.
observatory_stats	Yes	Get writing statistics: word counts, streaks, productivity.
observatory_moments	Yes	Get notable moments: breakthroughs, milestones, patterns.
observatory_ask	Yes	Ask AI about your writing patterns and story structure.
observatory_summary	Yes	Get an AI summary of your writing journey.
book_character_evolution	Yes	Get character evolution data for a book — emotional state, driving forces, chapter timeline, and ghost characters.

Marketplace

Browse and fork community-published characters, creatures, locations, plots, families, and books.

Tool	Auth	Description
marketplace_browse	No	Browse marketplace by entity type (characters, creatures, locations, plots, families, books).
marketplace_get	No	Get detailed view of a marketplace item.
marketplace_fork	Yes	Fork (copy) a marketplace item into your compendium.
marketplace_book_showcase	No	Get a published book's full showcase with author info and all entities.
marketplace_fork_book	Yes	Fork a published marketplace book and all its entities into your collection.

Library

Curated showcase books that demonstrate CivNode's world-building capabilities.

Tool	Auth	Description
library_books	No	List the 4 showcase books in the CivNode library.
library_fork_book	Yes	Fork a library book and all its entities into your collection.

Site Forum

The CivNode community forum at /forum, open to all users.

Tool	Auth	Description
forum_site_categories	No	List the six categories in the site-wide forum (Announcements, Writing Craft, Writing Groups, Competitions, Feedback & Ideas, Introductions).
forum_site_threads	No	List threads in the site-wide forum. Accepts optional category_id to filter by category and cursor for pagination.
forum_site_create_thread	Yes	Create a new thread in the site-wide forum. Requires title and body_markdown; optionally provide category_id.

Personal Forum

Every user on CivNode also has their own personal forum on their profile.

Tool	Auth	Description
forum_list_threads	No	List threads in a user's forum.
forum_read_thread	No	Read a thread with all posts.
forum_search	No	Search threads by keyword.
forum_post	Yes	Create a new thread or reply. Provide thread_id for replies, or forum_alias + title for new threads.

Competitions

Community writing competitions with signup, submission, and voting phases.

Tool	Auth	Description
list_competitions	No	List competitions. Filter by phase: signup, writing, voting, completed.
get_competition	Yes	Get competition details.
create_competition	Yes	Create a competition (requires supporter status).
competition_signup	Yes	Sign up for a competition.
competition_submit_entry	Yes	Submit your entry (writing phase only).
competition_vote	Yes	Vote for top 3 entries (voting phase only).
competition_entries	No	Get blind entries (voting/completed phase).
competition_results	No	Get ranked results (completed phase).

Collaboration

Real-time co-writing and draft sharing.

Tool	Auth	Description
create_share_link	Yes	Generate a shareable link for a work.
list_share_links	Yes	List share links for a work.
get_shared_work	No	Read a shared work by its token.
delete_share_link	Yes	Delete a share link.
list_collaborators	Yes	List collaborators on a work.
invite_collaborator	Yes	Invite a user as coauthor or editor.
accept_collaboration	Yes	Accept a collaboration invitation.
remove_collaborator	Yes	Remove a collaborator.

Groups, Topics & Community

Tool	Auth	Description
list_groups	Yes	List groups you belong to.
create_group	Yes	Create a new writing group. Types: critique, accountability, workshop, co_writing, sprint. Caller becomes owner.
get_group	Yes	Get group details.
group_update	Yes	Update a group's name and description (owner/leader only).
delete_group	Yes	Delete a group permanently (owner only). Removes all cycles, submissions, and rooms.
group_settings_get	Yes	Get feature settings for a group (caller must be a member). Returns submissions_enabled, reciprocity_mode, cycles_enabled, etc.
group_settings_update	Yes	Update feature settings for a group (owner/leader only). Pass any subset of: submissions_enabled, reciprocity_mode, silent_period_enabled, cycles_enabled, critique_templates_enabled, goals_enabled, sprints_enabled, challenges_enabled, project_tracking_enabled, directory_listed, member_cap.
group_add_member	Yes	Add a user to a group by user_id (owner/leader only).
group_remove_member	Yes	Remove a member from a group. Owner/leaders can remove anyone; members can remove themselves.
group_list_members	Yes	List all group members with roles (owner, leader, moderator, member).
group_promote_member	Yes	Promote or demote a member to a new role (leader, moderator, member). Owner can set any role; leaders can promote to moderator only.
group_transfer_ownership	Yes	Transfer ownership to another member (owner only). Former owner becomes leader.
group_warn_member	Yes	Issue a warning to a member with a required reason. Returns the warning and strike number. Moderators, leaders, and owner can warn.
group_list_warnings	Yes	List warnings issued to a specific member. Accessible by moderators, leaders, owner, or the member themselves.
group_ban_member	Yes	Ban a member from the group (leaders and owner only). Requires a reason. Member is removed immediately.
group_unban_member	Yes	Remove a ban on a user (owner only).
group_list_bans	Yes	List all currently banned members (owner and leaders only).
group_report	Yes	Report a group or specific member for a rules violation. Any group member can report.
list_topics	No	List topic communities.
join_topic	Yes	Join a topic.
leave_topic	Yes	Leave a topic.
get_encounter	Yes	Get today's encounter (daily anonymous pairing).
get_presence	No	See how many people are online (ambient count, no identities).

Messaging

Tool	Auth	Description
send_message	Yes	Send a message in a conversation.
list_conversations	Yes	List your conversations.
read_conversation	Yes	Read messages in a conversation.

Platform

Tool	Auth	Description
get_profile	No	Get a user's public profile.
update_tagline	Yes	Update your profile tagline (max 200 chars).
get_social_links	No	Get a user's social links.
update_social_links	Yes	Update your social links (replaces all).
update_avatar_source	Yes	Set avatar source (goavatar, gravatar, custom).
search_users	No	Search users by alias or name.
search_content	No	Search across all public content.
list_notifications	Yes	List your notifications.
mark_notifications_read	Yes	Mark all notifications as read.
list_bookmarks	Yes	List your bookmarks.
toggle_bookmark	Yes	Toggle a bookmark on content.
list_highlights	Yes	List your text highlights.
create_highlight	Yes	Highlight text on a monument or work.
delete_highlight	Yes	Delete a highlight.
get_notepad	Yes	Get your private notepad.
update_notepad	Yes	Update your notepad content.
get_supporter_status	Yes	Check supporter status.
supporter_checkout	Yes	Start Stripe checkout for supporter ($5/month).
supporter_cancel	Yes	Cancel supporter subscription.
purchase_checkout	Yes	Create Stripe checkout to purchase a book or work.
check_purchase	Yes	Check if current user has purchased a specific item.
list_my_purchases	Yes	List all purchases by current user.
get_author_balance	Yes	Get author earnings balance and lifetime totals.
list_author_sales	Yes	List all sales for current user as author.
ai_usage_log_local	Yes	Log local AI usage (Ollama, ComfyUI) from the browser.
link_preview	No	Get a rich preview for an internal CivNode URL. Returns title, author, image, and meta for published content.

Speech Writing

Deterministic speech metrics and chapter revision history for writers working on speeches. Every metric is computed from LanguageTool plus rule-based Go packages — no LLM calls anywhere in these tools.

Tool	Auth	Description
speech_analysis	Yes	Return speech metrics for a chapter: delivery time, word/syllable/sentence counts, LIX, Flesch-Kincaid, breath-test violations, filler words, passive voice, rhetorical devices, per-sentence timings. Results cached per content hash.
convert_to_speech	Yes	Flip a book's type to speech, enable speech_mode on every chapter, and trigger a first analysis pass. Reversible.
convert_from_speech	Yes	Revert a speech book back to story (or another target type) and clear speech_mode on every chapter.
list_revisions	Yes	List revision history for a chapter, newest first.
fetch_revision	Yes	Fetch a single revision's full body (ProseMirror JSON + plain text).
restore_revision	Yes	Restore a chapter to a previous revision. Snapshots current body first so nothing is lost.
list_speaker_notes	Yes	List anchored speaker notes on a chapter, sorted by anchor position.
create_speaker_note	Yes	Create a speaker note anchored to a chapter text range.

Example — run a full speech analysis on a chapter and print the delivery time:

mcp__civnode__speech_analysis({
  chapter_id: "8f3a...",
  audience_preset: "formal"
})

Example — convert an existing story book into a speech:

mcp__civnode__convert_to_speech({ book_id: "a1b2..." })

---

Admin Tools

Admin tools require a session token with admin role. They only appear when a token is configured.

Tool	Description
admin_health	System health: app status, migration version, DB/Redis connectivity.
admin_stats	System-wide statistics: users, works, monuments, forums, moderation.
admin_users	List all users with details and status.
admin_user_ban	Ban a user.
admin_user_unban	Unban a user.
admin_toggle_strategist	Toggle strategist role for a user (grants Civic Room access).
admin_moderation_queue	View flagged content awaiting review.
admin_ai_providers	List configured AI text providers.
admin_ai_provider_keys	List AI providers with partial API keys visible.
admin_image_providers	List image generation providers.
admin_embedding_providers	List embedding providers.
admin_ai_usage	AI token usage statistics.
ai_usage_log	Detailed AI usage log with filtering (date range, provider, action, local/cloud, success) and pagination.
ai_usage_export	Export AI usage data as CSV with the same filters.
ai_pricing_list	List AI pricing rules (per-model token and image prices).
ai_pricing_upsert	Create or update an AI pricing rule for a provider+model.
ai_pricing_delete	Delete an AI pricing rule by ID.
admin_test_ai_chat	Test AI chat pipeline with a prompt.
admin_test_embedding	Test embedding pipeline.
admin_test_ollama	Test local Ollama connectivity from the server.
admin_backups	List database backups.
admin_trigger_backup	Trigger an immediate backup.
admin_feedback	List user feedback and bug reports.
admin_site_settings	View site-wide settings.
admin_update_site_settings	Update site settings (registration, maintenance mode).
admin_research_stats	Research system statistics.
admin_botsim_state	Bot simulation state.
admin_botsim_bots	List simulated bots.
admin_botsim_tick	Trigger one simulation tick.
admin_images	List AI-generated images with moderation status.
admin_block_image	Block an AI-generated image.
admin_campaigns	List marketing campaigns.
admin_ornaments	List monument ornaments.
admin_captcha_stats	Captcha analytics: challenges, solve rates, country breakdown.
admin_captcha_recent_failures	Recent captcha failures with IP and country.
admin_takedown	Execute a takedown from a content report (delete file, log event, optionally ban hash).

File Manager

Tools for inspecting file storage. Require a session token.

Tool	Auth	Description
list_drawers	Yes	List all drawers owned by the authenticated user. Returns name, kind (user/book/work/collection/character/canvas), file count, and total size in bytes.
file_stats	Yes	Get storage quota summary: quota_bytes, used_bytes, plan (free/paid/grace), grace_until, upgrade_url, and a human-readable "X MB of Y MB used" string.

Civic Room (Admin / Strategist)

The Civic Room is a private workspace for platform strategists and admins to manage social media presence and coordinate.

Tool	Description
civic_room_get_notes	Get your private Civic Room notes.
civic_room_save_notes	Save your private Civic Room notes.
civic_room_overview	Get overview: recent posts, threads, canvases.
civic_room_threads	List civic threads.
civic_room_canvases	List civic canvases.
civic_room_list_channels	List social media channels.
civic_room_create_channel	Create a social media channel.
civic_room_update_channel	Update a social media channel.
civic_room_delete_channel	Delete a social media channel.
civic_room_list_posts	List social media posts. Filter by state and channel.
civic_room_create_post	Create a social media post targeting multiple channels.
civic_room_update_post	Update a draft/queued post.
civic_room_delete_post	Delete a draft/queued post.
civic_room_publish_post	Publish a post immediately to its platform.

---

Examples

Create a Screenplay

create_book({
  title: "The Last Lighthouse",
  book_type: "screenplay",
  screenplay_format: "feature_film"
})

Export a Screenplay as Final Draft (FDX)

export_book({
  id: "book-uuid-here",
  format: "fdx"
})

Export a Screenplay as Fountain

export_book({
  id: "book-uuid-here",
  format: "fountain"
})

Import a Fountain Screenplay

import_fountain({
  text: "Title: The Last Lighthouse\nCredit: Written by\nAuthor: Jane Doe\n\nINT. LIGHTHOUSE - NIGHT\n\nA lone KEEPER tends the light."
})

Get a Link Preview

link_preview({
  url: "/books/abc-123/read"
})

Browse the Library

library_books()

Fork a Library Book

library_fork_book({
  book_id: "book-uuid-here"
})

Create a Chapter Linked to a Plot Scene

create_chapter({
  book_id: "book-uuid-here",
  title: "The Crossing",
  chapter_type: "chapter",
  plot_scene_id: "scene-uuid-here"
})

Move a Plot Scene Between Acts

update_plot_scene({
  plot_id: "plot-uuid-here",
  scene_id: "scene-uuid-here",
  act_id: "target-act-uuid",
  sort_order: 2
})

Edit a Plot Scene's Summary

update_plot_scene({
  plot_id: "plot-uuid-here",
  scene_id: "scene-uuid-here",
  summary: "Elena arrives at the lighthouse"
})

Create a Beat Under a Scene

create_plot_beat({
  plot_id: "plot-uuid-here",
  scene_id: "scene-uuid-here",
  title: "Elena spots the keeper's lantern",
  description: "First glimpse of another soul on the island.",
  beat_type: "reveal"
})

Reorder Beats Within a Scene

reorder_plot_beats({
  plot_id: "plot-uuid-here",
  scene_id: "scene-uuid-here",
  items: [
    { id: "beat-uuid-a", sort_order: 1 },
    { id: "beat-uuid-b", sort_order: 2 },
    { id: "beat-uuid-c", sort_order: 3 }
  ]
})

---

Local Development

To run against a local CivNode instance:

CIVNODE_API_URL=http://localhost:9080 CIVNODE_SESSION_TOKEN=your-token npx @civnode/mcp

Or in your MCP client config:

{
  "mcpServers": {
    "civnode-local": {
      "command": "npx",
      "args": ["-y", "@civnode/mcp"],
      "env": {
        "CIVNODE_API_URL": "http://localhost:9080",
        "CIVNODE_SESSION_TOKEN": "your-local-token"
      }
    }
  }
}

Troubleshooting

"Authentication required" — Set the CIVNODE_SESSION_TOKEN environment variable. Get a token from Settings → API Token on CivNode.

"Forbidden" — Your token doesn't have permission for that action. Admin tools require admin role.

"Rate limit exceeded" — Wait a moment and retry. CivNode rate-limits API calls per user.

"API error: 404" — The resource doesn't exist or you don't have access. Check the UUID.

Admin tools not showing — Admin tools only appear when CIVNODE_SESSION_TOKEN is set. They also require server-side admin role.

Wrong API URL — By default the server connects to https://civnode.com. Set CIVNODE_API_URL for local development.

Contributing

Adding a New Tool

1. Add a tool object to the tools array in index.js (or the admin section for admin tools):

{
  name: "tool_name",
  description: "What it does. Mention auth requirement.",
  inputSchema: {
    type: "object",
    properties: {
      id: { type: "string", description: "Resource UUID" },
    },
    required: ["id"],
  },
  handler: (args) => fetchAPI(`/api/endpoint/${args.id}`),
},

2. Use the existing HTTP helpers: fetchAPI (GET), postAPI (POST), putAPI (PUT), patchAPI (PATCH), deleteAPI (DELETE).

3. Update the tool count in the header comment and package.json.

4. Test locally: CIVNODE_API_URL=http://localhost:9080 node index.js

5. Bump version in package.json and push to main — CI auto-publishes to npm.

License

MIT