Emacs Org-Mode MCP Server
The server provides MCP tools for managing Emacs org-mode tasks, journal entries, and projects with structured search, automatic formatting, and optional Emacs ediff approval before writes.
Task management: list, get, create, update, move, and search tasks in
tasks.org, with automatic section moves on TODO/DONE changes and lookup by CUSTOM_ID, ticket ID, or headline.Journal management: list, get, create, update, and search daily journal entries, organized by date with tags, ticket IDs, and links.
Project management: list, get, create, update, and search projects, plus linking tasks to projects and regenerating an index.org grouped by status.
Search across all data: find tasks, journal entries, or projects by keywords with concise, targeted results instead of full file reads.
Automatic metadata handling: auto-generates IDs, CREATED/MODIFIED/CLOSED timestamps, and maintains High Level Tasks checklist.
Visual approval: uses Emacs ediff to review proposed changes before writing; can be disabled via flag or environment variable.
Optional git autocommit: automatically commits org file changes when the org directory is a git repo.
MCP resources: exposes format guides and live views of active tasks, completed tasks, today's journal, and project index.
Diagnostics:
diagnostic_envshows server configuration and file paths for troubleshooting.
Allows interaction with Emacs org-mode, providing tools for managing tasks, journal entries, and projects in org-mode files, including listing, creating, updating, searching, and cross-linking.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Emacs Org-Mode MCP Server list my open tasks"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Emacs Org-Mode MCP Server
An MCP (Model Context Protocol) server that enables Claude to manage Emacs org-mode task lists, journal entries, and projects.
I use Emacs org-mode for organising myself. This mainly revolves around three
things: tasks.org as a tracked task list (active and completed), a
journal/ directory of daily journal files, and projects/ — one file per
project — for longer-running work. Over time I have been leveraging Claude for
bookkeeping and context-linking: reminding me to update a task, suggesting a
journal entry, or noting what I worked on since the last summary.
Claude was surprisingly capable at working with org-mode files directly, but as those files grew it started hitting token limits. A dedicated MCP solves that: tools return only the data Claude needs, structure is maintained correctly, and there is a built-in visual approval step via Emacs ediff before any write lands on disk.
Token Efficiency
Operation | Without MCP (Read/Edit) | With MCP |
Find a task | Read entire | Returns only the matching task |
Search tasks | Read file, Claude parses | Returns only matching results |
List tasks | Read entire file | Returns structured list |
Update task | Read file, generate Edit | Send task content, ediff for approval |
Input tokens — raw file contents never enter the conversation context. Output tokens — Claude passes parameters to the MCP rather than generating careful string-matched Edit calls. Context accumulation — MCP responses are much smaller than repeated file reads over a long conversation.
There is also a reliability benefit: the MCP handles org-mode parsing correctly every time, whereas Claude occasionally makes formatting errors with raw Edit operations.
Related MCP server: Emacs MCP Tools
Features
Task Management (
~/org/tasks.org)List, create, update, search, and move tasks
Automatic section movement when status changes (
TODO→DONE)Find tasks by
:CUSTOM_ID:, ticket ID (e.g.GH-123), or headlineAuto-maintained High Level Tasks checklist
Visual approval via Emacs ediff before writes
Journal Management (
~/org/journal/)List, create, update, and search journal entries
Date-based file organisation (
YYYYMMDDformat)Tag support (
:daily_summary:,:meeting:, etc.)Visual approval via Emacs ediff before writes
Project Management (
~/org/projects/)One org file per project (
<slug>.org)List, create, update, and search projects
Section-level updates (avoids rewriting entire files)
Cross-linking between projects, tasks, and journal entries
Auto-maintained
index.orgwith all projects grouped by statusStatus values:
active,planning,on-hold,completed
Prerequisites
Python 3.13+
uv for package management
Emacs org-mode files in
~/org/
Installation
cd ~/projects/emacs-org-mcp
# Install dependencies
uv syncConfiguration
Claude Desktop
Prerequisites:
Ensure
uvis in your PATH. Claude Desktop spawns processes without a login shell and may not inherit your shell's PATH. Use the full path touv(e.g./Users/yourname/.local/bin/uv) or add it to a system-wide location.Create the virtual environment first:
cd /path/to/emacs-org-mcp make sync # or: uv sync
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"emacs-org": {
"command": "/Users/yourname/.local/bin/uv",
"args": [
"--directory", "/path/to/emacs-org-mcp",
"run", "server.py"
],
"env": {
"ORG_DIR": "/path/to/org"
}
}
}
}Note: Replace
/Users/yourname/.local/bin/uvwith the output ofwhich uv. Ifuvis reliably in your PATH you can use just"uv".
Claude Code
Add to user scope (available across all projects):
claude mcp add --scope user emacs-org \
-- uv --directory /path/to/emacs-org-mcp run server.pyOr use the Makefile:
make mcp-installOr edit ~/.claude.json directly:
{
"mcpServers": {
"emacs-org": {
"command": "uv",
"args": [
"--directory", "/path/to/emacs-org-mcp",
"run", "server.py"
]
}
}
}Environment Variables
All settings can be overridden via environment variables or command-line flags:
Variable / Flag | Default | Description |
|
| Base org directory |
|
| Journal files directory |
|
| Project files directory |
|
| Directories walked for loose org files. The env var takes several, separated like |
|
| Section name for active/TODO tasks |
|
| Section name for completed/DONE tasks |
|
| Section name for the high-level task checklist |
|
| Visual approval via Emacs ediff |
|
| Commit each org file change to git, when the org directory is already a repo |
| (searches PATH) | Custom path to |
Ediff Approval
By default, all create and update operations present changes visually in Emacs using ediff before applying them. A new Emacs frame opens with a side-by-side diff; you can edit the proposed content (Buffer B) before approving.
Controls (from the ediff control buffer):
Key | Action |
| Approve — apply changes |
| Reject — discard changes |
| Quit — approves by default |
The frame and all buffers close automatically after your decision. If
emacsclient is not available or Emacs is not running, the server falls back
to auto-approve.
To disable ediff approval:
uv run server.py --no-ediff-approval
# or set EMACS_EDIFF_APPROVAL=false in the MCP server envAvailable Tools
Task Tools (10)
Tool | Description |
| List all tasks in a section ( |
| Get a task by |
| Create a new task from a complete org-formatted string |
| Replace a task; auto-moves between sections on status change |
| Move a task between sections without changing content |
| Move a task within its section — position is priority |
| One-off: sort the completed section newest-first by |
| Archive tasks out of |
| Search tasks by keyword across all sections |
| Counts per section and project, in about ten lines |
archive_tasks is for work that is finished and recorded, or abandoned. Emacs
does the move, so it needs a reachable emacsclient and has no fallback. Only
archive tasks the user named or confirmed: if they describe a class of tasks,
list the headlines and ask first. Archived tasks stay readable through
search_org, marked [archived], and nothing unarchives them.
Journal Tools (5)
Tool | Description |
| List entries for a date (defaults to today) |
| Get an entry by time ( |
| Create a new journal entry |
| Update an existing entry |
| Search entries across recent days |
Project Tools (7)
Tool | Description |
| List all projects, optionally filtered by status |
| Get a project by slug, |
| Create a new project file from a complete org-formatted string |
| Update project sections, properties, headline, or tags |
| Search across all project files |
| Add a task link to a project's Related Tasks section |
| Rebuild |
Cross-Scope Search (1)
Tool | Description |
| Search tasks, journal, projects and loose org files as one ranked set |
For open-ended recall, when you do not know in advance whether what you are
looking for was written up as a task, a journal entry or a design note. It is
also the only way to reach org content no other tool owns: archived work in
<name>_archive files, and loose .org files anywhere under the search roots.
Every result line names its scope, so you know which tool fetches it.
Other
Tool | Description |
| Show server configuration and file paths |
MCP Resources
The server exposes resources that Claude can read directly for format documentation and live data:
Resource URI | Description |
| Task format specification |
| Journal entry format specification |
| Project file format and cross-linking guide |
| Live view of active tasks |
| Live view of completed tasks |
| Today's journal entries |
| All projects grouped by status |
Configuring CLAUDE.md
Add this section to your ~/.claude/CLAUDE.md to instruct Claude to use the
MCP server for all org-mode operations:
## Emacs Org-Mode (Journal, Tasks, Projects)
**CRITICAL: Always use the `mcp__emacs-org__*` MCP tools** for all journal,
task, and project operations. Never use Read/Write/Edit tools or bash commands
directly on these files.
### Format Reference
The MCP server exposes authoritative format guides as resources:
- `emacs-org://guide/journal-format`
- `emacs-org://guide/task-format`
- `emacs-org://guide/project-format`Claude will fetch the detailed format documentation from those resources when
needed, so you do not need to duplicate it in CLAUDE.md.
Testing
# Run all tests
make test
# Verify the server responds to tools/list
make test-mcpLicense
MIT
Available Tools
19 toolscreate_journal_entryA
Create a new journal entry with format: ** HH:MM [TICKET-ID] headline :tags:. Always check for existing entries first using list_journal_entries to avoid duplicates. Include ticket IDs (GH-123), PR links ([[url][#123]]), and task links ([[file:~/org/tasks.org::#task-id][Display]]) as appropriate. Use current system time for timestamp. Common tags: daily_summary, meeting, decision, blocked. For format specifications, read emacs-org://guide/journal-format.
Inputs: content (required), headline (required), date, tags, +1 more.
create_projectA
Create a new project file from a complete org-formatted string. Auto-generates :ID: (UUID), :CREATED:, and defaults :STATUS: to 'planning'. The project_entry should include a level-1 heading, :PROPERTIES: drawer with :CUSTOM_ID:, and level-2 sections (Description, Design, Goals, etc.). For format specifications, read emacs-org://guide/project-format.
Inputs: project_entry (required).
create_taskA
Create a new task in a section. Provide the complete org-formatted task entry with PROPERTIES drawer and subsections. The :ID: property is auto-generated if not provided. Always search for duplicates before creating. CREATED and MODIFIED timestamps are managed automatically. For format specifications, read emacs-org://guide/task-format.
Inputs: section (required), task_entry (required).
diagnostic_envB
Diagnostic tool to check environment variables for ediff approval
Inputs: no named parameters.
get_journal_entryA
Get a specific journal entry by date and time or headline substring. Returns complete entry content. For format specifications, read emacs-org://guide/journal-format.
Inputs: date (required), identifier (required).
get_projectA
Get a specific project by identifier (slug like 'booklore', CUSTOM_ID like 'project-booklore', or title substring). Returns full project content including all properties and sections. For format specifications, read emacs-org://guide/project-format.
Inputs: identifier (required).
get_taskA
Get a specific task by identifier (#+NAME like 'task-gh-28', ticket ID like 'GH-28', or headline substring). Returns full task content including all properties, subsections, and task items. For format specifications, read emacs-org://guide/task-format.
Inputs: identifier (required), section.
link_task_to_projectA
Add a task link to a project's Related Tasks section. The task_link should be an org-mode link like '- [[file:~/org/tasks.org::#task-gh-28][GH-28 Task name]]'.
Inputs: task_link (required), project_identifier (required).
list_journal_entriesA
List all journal entries for a specific date. Returns entry times, headlines, content, and tags. Use this to check what's already logged before creating new entries to avoid duplicates. For format specifications, read emacs-org://guide/journal-format.
Inputs: date.
list_projectsC
List all projects, optionally filtered by status. Returns project titles, slugs, status, and description previews. For detailed format specifications, read the emacs-org://guide/project-format resource.
Inputs: status.
list_tasksA
List all tasks in a section of tasks.org. Returns task names, headlines, status, and full content. Use this to check for existing tasks before creating new ones, or to get an overview of work in progress. For detailed format specifications, read the emacs-org://guide/task-format resource.
Inputs: section (required).
move_taskA
Move a task between sections (e.g., Active to Completed) without modifying content.
Inputs: identifier (required), to_section (required), from_section (required).
regenerate_project_indexA
Regenerate ~/org/projects/index.org from all project files. Call this once after initial setup or if the index becomes out of sync.
Inputs: no named parameters.
search_journalA
Search journal entries by query string across recent days. Returns complete matching entries. Use this to find past work on a topic, review recent activity, or look up when something was done. Searches last 30 days by default.
Inputs: query (required), days_back.
search_projectsA
Search across all projects by query string. Case-insensitive substring match on project titles and all section content. Returns matching projects.
Inputs: query (required).
search_tasksA
Search tasks by query string across all sections. Returns complete matching tasks. Use this to check for existing tasks before creating new ones, or to find tasks related to a topic.
Inputs: query (required).
update_journal_entryA
Update an existing journal entry with new content. Finds the entry by time (HH:MM), using existing_headline to disambiguate if multiple entries share the same time. Use this to correct or enhance existing entries, or add forgotten details like task links. For format specifications, read emacs-org://guide/journal-format.
Inputs: date (required), time (required), content (required), headline (required), +3 more.
update_projectA
Update a project's section content, properties, headline, or tags. Supports section-level updates to avoid rewriting the entire file. At least one of section+content, properties, headline, or tags must be provided. Always updates :MODIFIED: timestamp automatically. For format specifications, read emacs-org://guide/project-format.
Inputs: identifier (required), tags, content, section, +2 more.
update_taskA
Update an existing task with new content. Provide the complete new task entry including all properties and subsections. Automatic behaviors: (1) TODO→DONE moves to Completed section and sets CLOSED timestamp, (2) DONE→TODO moves to Tasks section and clears CLOSED timestamp, (3) MODIFIED timestamp updated automatically. Preserve all PROPERTIES including :ID:, :CUSTOM_ID:, and :CREATED:. For format specifications, read emacs-org://guide/task-format.
Inputs: identifier (required), task_entry (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Tools are mostly distinct per resource and action, with clear descriptions separating get/list/search. Minor overlap exists between move_task and update_task (which can also move tasks via status changes), and diagnostic_env is unrelated to the org-mode domain.
The dominant verb_noun pattern is consistent across tasks, journal entries, and projects (get_, create_, update_, search_, list_). Exceptions like diagnostic_env and the varying resource names (task vs journal_entry) are minor deviations, but the overall pattern remains predictable.
At 19 tools, the set is on the heavy side for an MCP server covering three domains. Most tools have a clear purpose, but diagnostic_env is out of place and the paired list/search tools add some redundancy.
Tasks, journal entries, and projects all have create, read, and update coverage, but there are no delete operations for any resource type—an obvious lifecycle gap. Otherwise the core workflows are well covered.
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for generating rough-draft project plans from natural-language prompts.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseBqualityDmaintenanceAn MCP server that connects Claude with Todoist for complete task and project management through natural language.86203 npm246MIT
- AlicenseNot gradedqualityDmaintenanceEnables Claude Code to control a running Emacs instance via MCP, supporting file opening, Magit integration, and server status checks.4MIT
- AlicenseBqualityDmaintenanceAn MCP server that bridges Claude Code with Emacs via emacsclient, enabling buffer, file, org-mode, git, and diff operations.55MIT
- FlicenseNot gradedqualityDmaintenanceMCP server for project planning inside Claude. It tracks progress, knows your codebase, and resumes exactly where you left off every session.9 npm5-