story-vault-mcp
MCP server for Story Vault — a local-first writing app. This server lets any MCP-compatible AI client (Claude Desktop, Cursor, Cline, Qwen Chat, …) read and write your encrypted Story Vault project data: scenes, characters, world notes, ideas, the main story/manuscript, and project memory.
This is the Python distribution (uvx story-vault-mcp). The server itself is a
Node.js program; this package embeds it and launches it for you. Node.js >= 18 is
required on PATH.
Install / run
uvx story-vault-mcp
Or install with pip:
pip install story-vault-mcp
story-vault-mcp
Configuration
The server needs three environment variables (your vault PIN is used only to decrypt the database and is never exposed to the AI):
| Variable | Required | Purpose |
|---|---|---|
STORY_VAULT_PIN |
yes | Your vault PIN. |
STORY_VAULT_DATA_DIR |
no | Path to the vault data dir (default <cwd>/data). |
STORY_VAULT_PROJECT_ID |
no | Default project ID — tools can omit project_id. |
Claude Desktop
Edit claude_desktop_config.json:
{
"mcpServers": {
"story-vault": {
"command": "uvx",
"args": ["story-vault-mcp"],
"env": {
"STORY_VAULT_PIN": "your-pin",
"STORY_VAULT_PROJECT_ID": "1",
"STORY_VAULT_DATA_DIR": "C:/path/to/your/vault/data"
}
}
}
}
Other clients (Cursor, Cline, …)
Use the same command/args/env shape in the client's MCP configuration.
Tools
37 tools covering the full project surface — see the project's ARCHITECTURE.md
("MCP Server (External AI Access)" section) for the complete list. Highlights:
list_projects/get_project/create_project/update_projectlist_scenes/read_scene_content/create_scene/save_scene_version(writes prose)list_characters/create_character/update_characterlist_world_notes/create_world_notelist_ideas/create_ideaget_main_story/add_scene_to_story/reorder_main_storylist_memory/add_memory/search_memory
Security
- The PIN is consumed only to derive the SQLCipher key (scrypt, N=4096). No tool output contains it.
- User metadata, AI provider settings/API keys, and filesystem paths are never returned.
- Every call enforces project ownership against the vault's local user.
Building from source
# from the repo root: bundle the Node server and copy it into this package
pnpm build:mcp:npm
cp mcp/npm/dist/index.cjs mcp/python/story_vault_mcp/mcp_server.cjs
cd mcp/python && uv build
HTTP mode (optional)
story-vault-mcp --http starts a Streamable HTTP server on 127.0.0.1:3100/mcp
(port via STORY_VAULT_PORT).
1 maintainer
Metadata
1 maintainer
Release files for story-vault-mcp 2.0.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| story_vault_mcp-2.0.3.tar.gz | 488.7 kB | Without provenance | Details for story_vault_mcp-2.0.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| story_vault_mcp-2.0.3-py3-none-any.whl | Python 3 | none | any | Details for story_vault_mcp-2.0.3-py3-none-any.whl |
Total release size: 981.4 kB
Release files / story_vault_mcp-2.0.3.tar.gz
| Download URL | story_vault_mcp-2.0.3.tar.gz |
|---|---|
| Size | 488.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bb60f44db5b1134a8763d2db38a089573a25e9d479f8f5e3dafa83dfa3ac0984
|
|
BLAKE2b-256 checksum How to use checksums |
f06d89697dbdbe856b0862f6df9c8a9d1220f4fd8710458e52d5cdadaf59667a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / story_vault_mcp-2.0.3-py3-none-any.whl
| Download URL | story_vault_mcp-2.0.3-py3-none-any.whl |
|---|---|
| Size | 492.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b522dec9edefe03753df6e3c2b5a08f04055a226e016258039aca74052198e98
|
|
BLAKE2b-256 checksum How to use checksums |
63df2dfa71a0a119e92750e9e4d96fd4d823335df99e6ade7583e3323bf663b0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for story-vault-mcp 2.0.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
