Skip to main content
Glama
Emacs Org-Mode MCP Server
by scanner

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 tasks.org (1000+ lines)

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 headline

    • Auto-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 (YYYYMMDD format)

    • 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.org with all projects grouped by status

    • Status 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 sync

Configuration

Claude Desktop

Prerequisites:

  1. Ensure uv is in your PATH. Claude Desktop spawns processes without a login shell and may not inherit your shell's PATH. Use the full path to uv (e.g. /Users/yourname/.local/bin/uv) or add it to a system-wide location.

  2. 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/uv with the output of which uv. If uv is 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.py

Or use the Makefile:

make mcp-install

Or 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

ORG_DIR / --org-dir

~/org

Base org directory

JOURNAL_DIR / --journal-dir

$ORG_DIR/journal

Journal files directory

PROJECTS_DIR / --projects-dir

$ORG_DIR/projects

Project files directory

SEARCH_ROOTS / --search-root

$ORG_DIR

Directories walked for loose org files. The env var takes several, separated like PATH; the flag is repeatable

ACTIVE_SECTION / --active-section

Tasks

Section name for active/TODO tasks

COMPLETED_SECTION / --completed-section

Completed Tasks

Section name for completed/DONE tasks

HIGH_LEVEL_SECTION / --high-level-section

High Level Tasks (in order)

Section name for the high-level task checklist

EMACS_EDIFF_APPROVAL / --ediff-approval / --no-ediff-approval

true

Visual approval via Emacs ediff

GIT_AUTOCOMMIT / --git-autocommit / --no-git-autocommit

true

Commit each org file change to git, when the org directory is already a repo

EMACSCLIENT_PATH / --emacsclient-path

(searches PATH)

Custom path to emacsclient (optional)

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

C-c C-y

Approve — apply changes

C-c C-k

Reject — discard changes

q

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 env

Available Tools

Task Tools (10)

Tool

Description

list_tasks

List all tasks in a section (Tasks or Completed Tasks)

get_task

Get a task by :CUSTOM_ID:, ticket ID, or headline substring

create_task

Create a new task from a complete org-formatted string

update_task

Replace a task; auto-moves between sections on status change

move_task

Move a task between sections without changing content

reorder_task

Move a task within its section — position is priority

resort_completed_tasks

One-off: sort the completed section newest-first by :CLOSED:

archive_tasks

Archive tasks out of tasks.org via org's org-archive-subtree

search_tasks

Search tasks by keyword across all sections

org_stats

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_journal_entries

List entries for a date (defaults to today)

get_journal_entry

Get an entry by time (HH:MM) or headline substring

create_journal_entry

Create a new journal entry

update_journal_entry

Update an existing entry

search_journal

Search entries across recent days

Project Tools (7)

Tool

Description

list_projects

List all projects, optionally filtered by status

get_project

Get a project by slug, :CUSTOM_ID:, or title substring

create_project

Create a new project file from a complete org-formatted string

update_project

Update project sections, properties, headline, or tags

search_projects

Search across all project files

link_task_to_project

Add a task link to a project's Related Tasks section

regenerate_project_index

Rebuild index.org from all project files

Cross-Scope Search (1)

Tool

Description

search_org

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

diagnostic_env

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

emacs-org://guide/task-format

Task format specification

emacs-org://guide/journal-format

Journal entry format specification

emacs-org://guide/project-format

Project file format and cross-linking guide

org://tasks/active

Live view of active tasks

org://tasks/completed

Live view of completed tasks

org://journal/today

Today's journal entries

org://projects/index

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-mcp

License

MIT

Available Tools

19 tools
create_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.

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

    A3.6/5.0

    Scored across 19 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness3/5

    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

    Related MCP Servers