{"slug": "building-a-confluence-mcp-server-for-claude-code-from-setup-to-skills", "title": "Building a Confluence MCP Server for Claude Code: From Setup to Skills", "summary": "A developer built an open-source Confluence MCP server that allows Claude Code to automate Confluence workflows directly from the terminal. The server exposes tools for publishing pages, syncing content, and uploading images, using the Model Context Protocol to bridge AI assistants with external services. It validates credentials via Zod and registers with Claude Code through a .mcp.json configuration file.", "body_md": "Automate your Confluence workflow directly from Claude Code — publish pages, sync content, and upload images without leaving your terminal.\n\n**GitHub:** [https://github.com/tariqulislam/confluence-mcp-server](https://github.com/tariqulislam/confluence-mcp-server)\n\n**MCP** stands for **Model Context Protocol** — an open standard that lets AI assistants like Claude Code connect to external tools and services. An MCP server acts as a bridge: it exposes a set of *tools* that Claude Code can call, allowing it to interact with third-party systems (like Confluence) on your behalf.\n\nIn this guide you will learn:\n\n```\nconfluence-mcp-mock/\n├── .env                     ← your credentials (never committed)\n├── .env.example             ← template\n├── .mcp.json                ← registers MCP servers with Claude Code\n├── confluence-mcp/\n│   ├── src/\n│   │   ├── index.ts         ← entry point\n│   │   ├── server.ts        ← tool registration\n│   │   ├── config.ts        ← env validation (Zod)\n│   │   ├── confluence/\n│   │   │   ├── client.ts    ← Axios HTTP client\n│   │   │   ├── api.ts       ← REST API calls\n│   │   │   ├── parser.ts    ← XHTML to structured data\n│   │   │   └── markdown-converter.ts\n│   │   └── tools/           ← one file per MCP tool\n│   │       ├── connection-check.ts\n│   │       ├── list-pages.ts\n│   │       ├── publish-page.ts\n│   │       ├── read-save-page.ts\n│   │       ├── upload-images.ts\n│   │       └── sync-pages.ts\n│   └── build/               ← compiled output\n└── .claude/skills/          ← slash command definitions\n    ├── confluence-conn-check/\n    ├── confluence-page-list/\n    ├── publish-to-confluence/\n    ├── confluence-upload-images/\n    └── confluence-sync-pages/\n```\n\nThe server reads all credentials from a single `.env`\n\nfile at the project root. Copy the example template:\n\n```\ncp .env.example .env\n```\n\nThen fill in the four Confluence variables:\n\n```\n# .env  (never commit this file)\nCONFLUENCE_URL=https://your-confluence-instance.com/confluence/\nCONFLUENCE_USER=your.email@company.com\nCONFLUENCE_PERSONAL_ACCESS_TOKEN=your_token_here\nCONFLUENCE_SPACE_KEY=MYSPACE\n```\n\nThe four variables you need:\n\n**CONFLUENCE_URL** — Base URL of your Confluence instance. Must end with a trailing slash.\n\nExample: `https://confluence.company.com/confluence/`\n\n**CONFLUENCE_USER** — The email address tied to your Confluence account.\n\n**CONFLUENCE_PERSONAL_ACCESS_TOKEN** — A Bearer token generated in Confluence settings.\n\n**CONFLUENCE_SPACE_KEY** — The space key where new pages will be created. Example: `ENGINEERING`\n\nWhen the server starts, `config.ts`\n\nreads the `.env`\n\nfile and validates every variable using **Zod** — a TypeScript schema library. If any variable is missing or malformed, the server exits with a clear error instead of failing silently later.\n\n``` python\n// confluence-mcp/src/config.ts  (simplified)\nimport dotenv from 'dotenv';\nimport { z } from 'zod';\n\ndotenv.config({ path: join(__dirname, '..', '..', '.env') });\n\nconst envSchema = z.object({\n  CONFLUENCE_URL: z.string().url(),\n  CONFLUENCE_USER: z.string().email(),\n  CONFLUENCE_PERSONAL_ACCESS_TOKEN: z.string().min(1),\n  CONFLUENCE_SPACE_KEY: z.string().min(1),\n});\n\nexport const config = envSchema.parse(process.env);\n```\n\nThe validated config is imported by `client.ts`\n\n, which creates a single Axios instance used by every tool:\n\n``` js\n// confluence-mcp/src/confluence/client.ts  (simplified)\nconst client = axios.create({\n  baseURL: config.CONFLUENCE_URL,\n  headers: {\n    Authorization: `Bearer ${config.CONFLUENCE_PERSONAL_ACCESS_TOKEN}`,\n    Accept: 'application/json',\n    'Content-Type': 'application/json',\n  },\n  timeout: 30000,\n});\n```\n\nCredentials are set once here and never repeated anywhere else in the codebase.\n\nClaude Code discovers MCP servers through the `.mcp.json`\n\nfile in the project root:\n\n```\n{\n  \"mcpServers\": {\n    \"confluence\": {\n      \"command\": \"node\",\n      \"args\": [\"./confluence-mcp/build/index.js\"]\n    }\n  }\n}\n```\n\nThis tells Claude Code: *\"When this project is open, launch the node process at that path and communicate with it over stdio.\"*\n\n```\n# Install dependencies\ncd confluence-mcp && npm install\n\n# Compile TypeScript to JavaScript\nnpm run build\n\n# Restart Claude Code to load the new server\n```\n\nDuring development, use watch mode so the server recompiles on every save:\n\n```\nnpm run watch\n```\n\nThe server follows a clean three-layer pattern:\n\n```\nClaude Code\n    │  (MCP protocol over stdio)\n    ▼\nserver.ts         ← registers tools, routes calls\n    │\n    ▼\ntools/*.ts        ← one file per tool, handles input/output\n    │\n    ▼\nconfluence/api.ts ← REST API calls (Confluence v1 endpoints)\n```\n\n`server.ts`\n\ndeclares every tool's name, description, and input schema in the `ListToolsRequestSchema`\n\nhandler. Claude Code reads this to understand what tools exist. Calls are then routed in the `CallToolRequestSchema`\n\nhandler:\n\n```\n// server.ts  (simplified)\nserver.setRequestHandler(ListToolsRequestSchema, async () => ({\n  tools: [\n    {\n      name: 'confluence_connection_check',\n      description: 'Verify connection to Confluence and check authentication.',\n      inputSchema: { type: 'object', properties: {}, required: [] },\n    },\n    {\n      name: 'confluence_list_pages',\n      description: 'List all child pages under a parent page.',\n      inputSchema: {\n        type: 'object',\n        properties: {\n          parent_page_id: { type: 'string', description: 'ID of the parent page' },\n        },\n        required: ['parent_page_id'],\n      },\n    },\n  ],\n}));\n\nserver.setRequestHandler(CallToolRequestSchema, async (request) => {\n  switch (request.params.name) {\n    case 'confluence_connection_check':\n      return { content: [{ type: 'text', text: await handleConnectionCheck() }] };\n    case 'confluence_list_pages':\n      return { content: [{ type: 'text', text: await handleListPages(args) }] };\n  }\n});\n```\n\n**confluence_connection_check** — Verifies auth and returns server/user info\n\n**confluence_list_pages** — Lists all child pages under a parent\n\n**confluence_read_save_page** — Downloads a page (sections, tables, images, comments) to local JSON\n\n**confluence_publish_page** — Converts markdown to Confluence XHTML and creates/updates a page\n\n**confluence_upload_images** — Bulk-uploads images from a local directory as page attachments\n\n**confluence_sync_pages** — Syncs all child pages to local markdown with change tracking\n\nSkills are the user-friendly layer on top of raw MCP tools. A skill is a directory under `.claude/skills/`\n\ncontaining a `SKILL.md`\n\nfile.\n\n```\n.claude/skills/confluence-conn-check/\n└── SKILL.md\n---\nname: confluence-conn-check\ndescription: Verify Confluence server connection and authentication.\nargument-hint: (no arguments required)\n---\n\n# Confluence Connection Check\n\nTest the connection to Confluence and verify your credentials.\n\n## Usage\n\n/confluence-conn-check\n\n## MCP Tool\n\nconfluence_connection_check\n```\n\nThe three frontmatter fields that matter:\n\n**name** — becomes the slash command (e.g. `/confluence-conn-check`\n\n)\n\n**description** — shown in the `/`\n\nautocomplete menu and used for auto-discovery by Claude\n\n**argument-hint** — hint shown in autocomplete, e.g. `<parent_page_id>`\n\nor `(no arguments required)`\n\nWhen you type `/confluence-conn-check`\n\nin Claude Code, it reads `SKILL.md`\n\n, knows which MCP tool to call, and formats the response back to you.\n\nVerify your credentials before doing anything else.\n\n```\n/confluence-conn-check\n```\n\nExpected response:\n\n```\n{\n  \"status\": \"success\",\n  \"user\": {\n    \"displayName\": \"Jane Doe\",\n    \"email\": \"jane.doe@company.com\"\n  },\n  \"server\": {\n    \"version\": \"8.5.0\",\n    \"baseUrl\": \"https://confluence.company.com/confluence\"\n  }\n}\n```\n\nList all child pages under a parent so you can find page IDs.\n\n```\n/confluence-page-list 123456789\n```\n\nResponse:\n\n```\n{\n  \"status\": \"success\",\n  \"message\": \"Found 3 child page(s)\",\n  \"pages\": [\n    { \"id\": \"987654321\", \"title\": \"Getting Started\" },\n    { \"id\": \"987654322\", \"title\": \"API Reference\" }\n  ]\n}\n```\n\nDownload a full page — sections, tables, images, and comments — and save it locally as structured JSON.\n\n```\n/confluence-page-read-save-content 987654321\n```\n\nSaves to:\n\n```\nconfluence-docs/con_<parentId>_<pageId>/\n├── sections_and_sub_sections_contents.json\n├── comments_contents.json\n└── images/\n    ├── screenshot.png\n    └── diagram.jpg\n```\n\nConvert a markdown file to Confluence storage format and publish it. Images referenced in the markdown are automatically uploaded as attachments.\n\nCreate a new page:\n\n```\n/publish-to-confluence 123456789 docs/architecture.md\n```\n\nUpdate an existing page:\n\n```\n/publish-to-confluence 123456789 docs/architecture.md 987654321\n```\n\nThe markdown converter handles headings, bold/italic, fenced code blocks with syntax highlighting, ordered and unordered lists (nested), pipe tables, local and external images, blockquotes, and horizontal rules.\n\nBulk-upload images from a local directory with configurable rate-limit control.\n\n```\n# Default (3 parallel, 2 s delay between batches)\n/confluence-upload-images 987654321 ./screenshots\n\n# Conservative — slow instance or large files\n/confluence-upload-images 987654321 ./screenshots 1 3000\n```\n\nRate-limit tuning guide:\n\n`batch_size=1, delay_ms=3000`\n\n— safest, use on aggressive instances`batch_size=3, delay_ms=2000`\n\n— default, works for most instances`batch_size=5, delay_ms=1000`\n\n— faster, for lightly loaded on-premise serversDownload all child pages under a parent as local markdown files. On repeat runs, only pages that actually changed (version bump or new attachment) are re-downloaded.\n\n```\n/confluence-sync-pages 6656101928\n```\n\nOutput structure:\n\n```\nconfluence_doc_md/\n└── parent_6656101928/\n    ├── manifest.json      ← change-tracking index\n    ├── page_987654321/\n    │   ├── page.md\n    │   ├── comments.json\n    │   └── images/\n    └── page_987654322/\n        └── page.md\n```\n\nEach `page.md`\n\nstarts with a metadata header:\n\n```\n# Page Title\n\n> Page ID: 987654321\n> Version: 5\n> Last modified: 2026-05-20T10:30:00.000Z\n\n[page body]\n\n---\n\n## Comments\n\n### Comment by jane.doe (2026-05-19T09:00:00.000Z)\n\nComment text here.\n```\n\nChange detection logic:\n\n```\n# 1. Verify credentials\n/confluence-conn-check\n\n# 2. Find the parent page ID\n/confluence-page-list 100000001\n\n# 3. Write docs locally in your editor\n# (create docs/my-feature.md)\n\n# 4. Publish\n/publish-to-confluence 100000002 docs/my-feature.md\n\n# 5. Update after edits\n/publish-to-confluence 100000002 docs/my-feature.md 987654321\n\n# 6. Back up all pages under a parent\n/confluence-sync-pages 100000001\n```\n\nTo extend the server with a custom tool, follow four steps.\n\n**1. Create the tool file** at `confluence-mcp/src/tools/your-tool.ts`\n\n:\n\n``` js\nimport { z } from 'zod';\n\nexport const yourToolSchema = z.object({\n  page_id: z.string().describe('The Confluence page ID'),\n});\n\nexport async function handleYourTool(input: z.infer<typeof yourToolSchema>) {\n  return JSON.stringify({ status: 'success', data: {} }, null, 2);\n}\n```\n\n**2. Register in server.ts** — add to the tool list and the switch statement:\n\n``` js\nimport { handleYourTool } from './tools/your-tool.js';\n\n// in ListToolsRequestSchema handler:\n{ name: 'confluence_your_tool', description: '...', inputSchema: { ... } }\n\n// in CallToolRequestSchema handler:\ncase 'confluence_your_tool':\n  return { content: [{ type: 'text', text: await handleYourTool(args) }] };\n```\n\n**3. Create the skill** at `.claude/skills/your-tool/SKILL.md`\n\nfollowing the format in Step 6.\n\n**4. Rebuild and restart:**\n\n```\ncd confluence-mcp && npm run build\n# Restart Claude Code\n```\n\n**MCP server not loading**\n\nRun `npm run build`\n\ninside `confluence-mcp/`\n\nand check for TypeScript errors. Verify `.mcp.json`\n\npoints to `./confluence-mcp/build/index.js`\n\n. Fully restart Claude Code — the server process is launched at startup.\n\n**401 Authentication Error**\n\nRegenerate your Personal Access Token in Confluence settings. Confirm `CONFLUENCE_USER`\n\nis the email associated with the token.\n\n**URL errors**\n\n`CONFLUENCE_URL`\n\nmust end with a trailing slash. If behind a VPN, connect before running.\n\n**Publishing formatting issues**\n\nTables need a header separator row (`|---|---|`\n\n). Avoid emoji and raw angle bracket characters (`<`\n\n, `>`\n\n) directly inside table cells — Confluence's XHTML parser rejects them.\n\n**Rate limit exceeded during image upload**\n\nSlow down: `/confluence-upload-images <page_id> <dir> 1 4000`\n\nThe full stack in one view:\n\n`.env`\n\n— credentials, never committed`config.ts`\n\n— Zod validates env at startup`client.ts`\n\n— single Axios instance with Bearer auth`api.ts`\n\n— Confluence REST v1 endpoint calls`tools/*.ts`\n\n— one handler per MCP tool`server.ts`\n\n— declares tools to Claude Code via MCP protocol`.mcp.json`\n\n— tells Claude Code where to find the server`.claude/skills/*/SKILL.md`\n\n— slash commands that wrap MCP toolsWith this architecture you can publish markdown documentation, sync entire Confluence spaces, and upload images — all from a single Claude Code session.\n\n**Source code:** [github.com/tariqulislam/confluence-mcp-server](https://github.com/tariqulislam/confluence-mcp-server)", "url": "https://wpnews.pro/news/building-a-confluence-mcp-server-for-claude-code-from-setup-to-skills", "canonical_source": "https://dev.to/tariqulislam/-building-a-confluence-mcp-server-for-claude-code-from-setup-to-skills-k95", "published_at": "2026-06-16 14:32:23+00:00", "updated_at": "2026-06-16 14:47:16.430840+00:00", "lang": "en", "topics": ["developer-tools", "artificial-intelligence", "large-language-models", "ai-agents"], "entities": ["Claude Code", "Confluence", "Model Context Protocol", "GitHub", "Zod", "Axios"], "alternates": {"html": "https://wpnews.pro/news/building-a-confluence-mcp-server-for-claude-code-from-setup-to-skills", "markdown": "https://wpnews.pro/news/building-a-confluence-mcp-server-for-claude-code-from-setup-to-skills.md", "text": "https://wpnews.pro/news/building-a-confluence-mcp-server-for-claude-code-from-setup-to-skills.txt", "jsonld": "https://wpnews.pro/news/building-a-confluence-mcp-server-for-claude-code-from-setup-to-skills.jsonld"}}