Document MCP gives writers, researchers, and knowledge-managers first-class control over large-scale Markdown documents with built-in safety features that prevent content loss. Manage books, research papers, and documentation with 32 AI-powered tools.
For Claude Desktop users - No installation required. Just add to your Claude Desktop config:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"document-mcp": {
"url": "https://document-mcp-451560119112.asia-east1.run.app"
}
}
}Restart Claude Desktop. When you first connect:
- Your browser opens for Google OAuth authentication
- Sign in with your Google account
- Claude Desktop securely stores your access token
- Start managing documents immediately!
What you get:
- 32 MCP tools for document management
- Your own isolated document storage
- Automatic snapshots and version control
- No setup, no API keys, no maintenance
For Claude Code users or those who want local document storage:
pip install document-mcpAdd to your Claude Code MCP settings:
{
"mcpServers": {
"document-mcp": {
"command": "python",
"args": ["-m", "document_mcp.doc_tool_server", "stdio"]
}
}
}See the Package Installation Guide for detailed setup with universal path finding.
Document MCP provides a structured way to manage large documents composed of multiple chapters. Think of it as a file system specifically designed for books, research papers, documentation, or any content that benefits from being split into manageable sections.
- 32 MCP Tools: Document management, chapter operations, paragraph editing, semantic search, metadata, and version control
- Built-in Safety: Automatic snapshots before destructive operations, version history, and conflict detection
- Pagination System: Page-based content access for large documents (50K chars per page)
- User Isolation: Each authenticated user gets their own isolated storage (hosted version)
- Local-First Option: Keep your documents on your own machine (PyPI version)
.documents_storage/
├── my_novel/ # A document
│ ├── 01-prologue.md # Chapters ordered by filename
│ ├── 02-chapter-one.md
│ └── 03-chapter-two.md
└── research_paper/ # Another document
├── 00-abstract.md
├── 01-introduction.md
└── 02-methodology.md
Document MCP includes safety features designed to prevent content loss:
- Automatic Snapshots: Created before every destructive operation
- Named Checkpoints: Create restore points with
snapshot_document - Version Restoration: Roll back to any previous version with
restore_snapshot - Conflict Detection: Warns about potential overwrites from external modifications
- Audit Trail: Complete modification history with timestamps
The hosted version runs on Google Cloud Run:
| Feature | Details |
|---|---|
| Authentication | OAuth 2.1 with PKCE via Google |
| Region | asia-east1 (Taiwan) |
| Scaling | Auto-scales 0-10 instances based on load |
| Cost | Free for users (scales to zero when idle) |
Document MCP provides 32 tools organized into 8 categories:
| Category | Tools | Description |
|---|---|---|
| Document | 6 | Create, delete, list documents; manage summaries |
| Chapter | 4 | Add, edit, delete, list chapters with frontmatter |
| Paragraph | 8 | Atomic paragraph operations (insert, replace, delete, move) |
| Content | 6 | Read, search, replace, statistics, semantic search, entity tracking |
| Metadata | 3 | Chapter frontmatter, entities, timeline management |
| Safety | 3 | Snapshots, restore, diff comparison |
| Overview | 1 | Document outline with metadata |
| Discovery | 1 | Tool search and discovery |
👤 User: Create a new document called 'My Novel'
🤖 Claude: ✅ Created document 'My Novel'
👤 User: Add a chapter called '01-introduction.md' with content '# Chapter 1\n\nIt was a dark and stormy night...'
🤖 Claude: ✅ Created chapter '01-introduction.md' in 'My Novel'
👤 User: List all my documents
🤖 Claude: ✅ Found 1 document: 'My Novel' with 1 chapter
👤 User: Delete paragraph 3 from chapter '02-climax.md' in 'My Novel'
🤖 Claude: ✅ Deleted paragraph 3. Automatic snapshot created for recovery.
👤 User: Actually, restore the last snapshot
🤖 Claude: ✅ Restored from snapshot. Paragraph 3 is back.
👤 User: Find content similar to "the hero's journey" in my novel
🤖 Claude: ✅ Found 3 paragraphs with similar themes:
- Chapter 2, paragraph 5 (similarity: 0.89)
- Chapter 4, paragraph 12 (similarity: 0.82)
- Chapter 1, paragraph 3 (similarity: 0.78)
- Python 3.10+
- Git
# Clone the repository
git clone https://github.com/clchinkc/document-mcp.git
cd document-mcp
# Install with uv (recommended)
uv sync
# Or with pip
pip install -e ".[dev]"# All tests (528 tests)
uv run pytest
# By tier
uv run pytest tests/unit/ # Fast, isolated tests
uv run pytest tests/integration/ # Real MCP, mocked LLM
uv run pytest tests/e2e/ # Full system (requires API keys)
# Code quality
uv run ruff check --fix && uv run ruff format
uv run mypy document_mcp/# Start MCP server
uv run python -m document_mcp.doc_tool_server stdio
# Or with PyPI installation
document-mcp stdio| Guide | Description |
|---|---|
| Package Installation | PyPI setup for Claude Code |
| Manual Testing | Creative writing workflows |
| MCP Design Patterns | Production patterns and best practices |
| Testing Strategy | 4-tier testing architecture |
Contributions welcome! Please run the test suite before submitting PRs:
uv run pytest && uv run ruff check && uv run mypy document_mcp/MIT License - see LICENSE for details.
- Built with Model Context Protocol (MCP)
- Powered by Pydantic AI
- Hosted on Google Cloud Run
⭐ Star this repo if you find it useful!