amber-confluence-mcp

What it does

You keep your documentation in a Confluence your company hosts itself. You would like to edit a page in your own editor, diff it, or let an agent update it — and you cannot, because Atlassian's tooling only talks to Confluence Cloud.

$ amber confluence pull 100000001        # page becomes Markdown
$ code ~/amber/pages/100000001.md        # edit it however you like
$ amber confluence diff 100000001        # see exactly what will change
$ amber confluence push 100000001        # publish it back

Your macros, panels, attachments and layouts survive all of that untouched.

Related MCP server: Confluence MCP Server

Contents

• Install · Set it up · Everyday use

• How macros survive

• When it says no

• Use it from an agent

• Check your instance first · Company certificates, slow proxies

• What has been tested, and what has not

• What it cannot do yet · Troubleshooting

Install

npm install -g amber-confluence

Node 18 or newer. Nothing else: no runtime dependencies at all.

Set it up

1. Tell it where your Confluence lives. Create ~/.config/amber/config.toml:

[confluence]
url  = "https://wiki.example.com"
user = "you@example.com"          # leave out if you use a token

2. Give it a credential. Which one depends on your Confluence version:

The credential goes into your keychain, never into the config file:

# with a token
security add-generic-password -s amber-confluence-token -a 'you@example.com' -w

# with a password
security add-generic-password -s amber-confluence -a 'you@example.com' -w

On Linux the same values go into secret-tool under the same service names. In a hurry, AMBER_CONFLUENCE_TOKEN or AMBER_CONFLUENCE_PASSWORD work for one command.

3. Try it on a page. Any page id, or the URL straight from your browser:

$ amber confluence pull https://wiki.example.com/pages/viewpage.action?pageId=100000001
Onboarding  (v12, space DEMO)
/Users/you/amber/pages/100000001.md
3 opaque block(s): ⟦macro.toc#1⟧ ⟦macro.warning#1⟧ ⟦macro.status#1⟧

Everyday use

<page> is a page id or any Confluence URL containing one. Add -m "why" to push to leave a comment in the page history, and --json to any command to get output a script can read.

A pulled page is ordinary Markdown with a small header, so it opens anywhere and can live in git:

---
amber: confluence
page_id: 100000001
title: Onboarding
space: DEMO
version: 12
pulled_at: 2026-09-20T10:14:00Z
digest: sha256:9f2ac41b8e5d7a03
---

# Onboarding

How macros survive

Confluence stores pages in a markup that Markdown cannot express. Most converters try to rebuild that markup afterwards, and that is where macros get mangled.

This one never rebuilds anything. Whatever Markdown cannot carry is lifted out before conversion and put back byte for byte afterwards. In your text you see a marker where it used to be:

⟦macro.warning#1⟧

## Use cases

| # | Case | Status |
|---|---|---|
| UC1 | Sign-up from the landing page | ⟦macro.status#1⟧ |

Move a marker, copy it, delete it — all fine. You cannot damage what it stands for, because its contents never pass through the conversion at all.

When it says no

Two situations where publishing would quietly destroy something. Both stop, explain themselves, and exit with status 2 so scripts can tell a refusal from a crash.

Someone edited the page while you were working.

$ amber confluence push 100000001
Refusing to publish: the page changed after you pulled it.
  your copy: v12
  on the server: v14, last edited by John Doe at 2026-09-20T09:14:00Z

Pull again and reapply your edit, or repeat with force to overwrite their work.

A marker went missing from your Markdown. That macro, panel or attachment would disappear from the page. The message names every block that went.

Both can be overridden with --force when you actually mean it.

And when nothing changed, nothing is sent: pushing a page you did not edit adds no version to its history. A newline your editor appended on save, or Windows line endings, do not count as an edit.

Use it from an agent

The MCP server exposes the same four operations, with the same refusals. For Claude Desktop, Claude Code, or any other MCP client:

{
  "mcpServers": {
    "confluence": {
      "command": "amber-confluence-mcp",
      "env": {
        "AMBER_CONFLUENCE_URL": "https://wiki.example.com",
        "AMBER_CONFLUENCE_USER": "you@example.com"
      }
    }
  }
}

Refusals reach the agent as readable text rather than as errors, so it can pull again or put a marker back instead of giving up.

Check your instance first

$ amber confluence doctor 100000001
  ✓ Node v22.15.0
  ✓ Configuration read, signing in with personal access token
  ✓ Trusting the system store
  ✓ Reached Confluence 8.5.4 in 41 ms
  ✓ Signed in as John Doe
  ✓ Page converts there and back byte for byte (3 opaque block(s))

All good.

The doctor never writes. It checks the certificate, the version, whether your credential fits that version, the sign-in, and converts one page there and back in memory. --share prints the same report without the host, the account or any page content, safe to paste into an issue.

Company certificates, slow proxies

Self-hosted Confluence usually sits behind a certificate your company issued itself. The tool trusts the operating system's certificate store as well as Node's own list, so if your browser opens the wiki without a warning, this usually does too. If not:

[confluence]
url     = "https://wiki.example.com"
ca_file = "/path/to/company-root-ca.pem"
timeout = 120          # seconds; the default is 30

Certificate checks are never switched off.

What has been tested, and what has not

Round trips on real pages from public self-hosted instances, read only:

Against a stand-in instance that misbehaves on purpose: a context path behind a reverse proxy, compressed responses, rate limiting, single sign-on in front, a CAPTCHA lock, a self-signed certificate, http:// redirecting to https://, a server that never answers, and error messages in another language. Each of these failed or misled before it was fixed, and each is now a test.

Not tested yet: publishing to a real instance, Confluence 7.x and 8.x on real servers, and Windows. If you run any of these, TESTING.md is a twenty-minute walk-through that only touches a copy you make yourself, and docs/compatibility.md lists every reported run.

What it cannot do yet

A single page, out and back. Not yet here: pulling a tree of pages, uploading or replacing attachments, creating new pages. Confluence Cloud is out of scope — Atlassian's own tooling covers it.

Troubleshooting

Older instances have no personal access tokens. If yours is below Data Center 7.9, store the password instead of a token, under the amber-confluence service.

That is a login page. Usually single sign-on sits in front of the instance, or the session the credential belongs to has expired.

Nested blocks can report this. Pull the page again and push it back unedited: if the same list appears, the blocks are nested and --force is safe here.

~/amber/pages/<page id>.md, next to a hidden sidecar holding the opaque blocks. Change the location with pages_dir in the config file.

Contributing

Issues and pull requests are welcome. The most useful bug report carries the piece of Confluence markup that survived a round trip badly — with anything confidential taken out first.

npm test          # no network, no Confluence instance needed

License

MIT — see LICENSE.