word-footnotes-bibliography-mcp

A self-contained Model Context Protocol server that adds footnotes, in-text citations, and a bibliography / references / works-cited section to Microsoft Word .docx files — without Word.

Styles: APA 7, MLA 9, Chicago 17 (author-date and notes). Transport: stdio.

Prefer a Claude skill (SKILL.md + a CLI, no server) with the same capabilities? See the companion repo word-footnotes-bibliography-skill.

What's in here

word-footnotes-bibliography-mcp/
├── server.py            the MCP server (10 tools)
├── docx_fnbib/          the engine (python-docx + lxml) — importable on its own
├── pyproject.toml       installs `docx-fnbib-mcp` console script
├── requirements.txt
├── examples/build_demo.py
└── tests/               pytest suite (13 tests)

Related MCP server: mcp-server-docx

Install

git clone https://github.com/<you>/word-footnotes-bibliography-mcp
cd word-footnotes-bibliography-mcp
pip install -e .            # or: pip install -r requirements.txt

Requires Python 3.10+ and the mcp SDK v2 (MCPServer). For SDK v1, change the import in server.py to from mcp.server.fastmcp import FastMCP — the tool API is identical.

Run

docx-fnbib-mcp            # console script (after pip install -e .)
python server.py         # or run the module directly

Register with a client

{
  "mcpServers": {
    "docx-fnbib": { "command": "docx-fnbib-mcp" }
  }
}

Without installing the console script:

{
  "mcpServers": {
    "docx-fnbib": {
      "command": "python",
      "args": ["/absolute/path/to/word-footnotes-bibliography-mcp/server.py"]
    }
  }
}

Tools

Styles: apa, mla, chicago-author-date, chicago-notes. Modes: text (formatted by the server) or field (Word CITATION / BIBLIOGRAPHY fields the user refreshes in Word).

Paths resolve on the machine running the server; edits are in place unless an out path is passed.

Example session

create_document {path: "paper.docx", title: "Draft", paragraphs: ["A claim.", "Another point about Rome."]}
add_source      {path: "paper.docx", source: {tag: "Syme1939", type: "Book", authors: ["Syme, Ronald"], title: "The Roman Revolution", year: "1939", city: "Oxford", publisher: "Clarendon Press"}}
add_footnote    {path: "paper.docx", paragraph_index: 2, text: "Founded 753 BC.", anchor: "Rome"}
add_citation    {path: "paper.docx", paragraph_index: 1, tag: "Syme1939", style: "chicago-notes", page: "47"}
add_bibliography{path: "paper.docx", style: "chicago-author-date", heading: "Bibliography"}

How it works (short version)

• Footnotes — creates word/footnotes.xml, the separator notes, the FootnoteText / FootnoteReference styles, and numbered reference marks. Reopen-safe: numbering continues from existing notes.

• Sources — stored in Word's native customXml bibliography part (b: namespace), so References ▸ Manage Sources in Word sees them.

• Rendering — text mode formats entries itself (italic titles, hanging indent, sorted); field mode writes Word fields and sets SelectedStyle. chicago-notes emits real footnotes.

Run the tests

pip install -e ".[test]"
pytest

Limitations

• field mode needs desktop Word to render; elsewhere fields show cached text.

• The text formatter covers common source types well but is not a full CSL engine.

• Endnotes: create as footnotes, then Convert Notes in Word.

• Verify important documents open cleanly in your target Word version.

License

MIT — see LICENSE.