# finviet-confluence-mcp

An MCP (Model Context Protocol) server that lets AI agents read Confluence page content by URL. Supports self-hosted Confluence with basic auth.

## Tool exposed

| Tool | Description |
|---|---|
| `read_confluence_page` | Fetch a Confluence page by URL and return its title, space, version, and plain-text content |

Supported URL formats:
- `https://kb.finviet.com.vn/pages/viewpage.action?pageId=12345`
- `https://kb.finviet.com.vn/pages/12345/Page-Title`
- `https://kb.finviet.com.vn/display/SPACE/Page+Title`

---

## Prerequisites

- Node.js 18 or later
- Access to a Confluence instance (self-hosted or Cloud) with valid credentials

---

## Setup

### 1. Clone and install dependencies

```bash
git clone https://github.com/dobadevv/finviet-confluence-mcp.git
cd finviet-confluence-mcp
npm install
```

### 2. Build

```bash
npm run build
```

The compiled output lands in `dist/`.

### 3. Verify (optional)

```bash
CONFLUENCE_BASE_URL=https://kb.finviet.com.vn \
CONFLUENCE_USERNAME=your-username \
CONFLUENCE_PASSWORD=your-password \
node dist/index.js
```

You should see:
```
finviet-confluence-mcp server started (stdio)
```

---

## Configuration

The server reads credentials from environment variables at startup:

| Variable | Required | Example |
|---|---|---|
| `CONFLUENCE_BASE_URL` | Yes | `https://kb.finviet.com.vn` |
| `CONFLUENCE_USERNAME` | Yes | `john.doe` |
| `CONFLUENCE_PASSWORD` | Yes | `s3cr3t` |

---

## Adding to your agent

### Cursor

Open **Cursor Settings → MCP** (or edit `~/.cursor/mcp.json`) and add:

```json
{
  "mcpServers": {
    "finviet_confluence": {
      "command": "node",
      "args": ["/absolute/path/to/finviet-confluence-mcp/dist/index.js"],
      "env": {
        "CONFLUENCE_BASE_URL": "https://kb.finviet.com.vn",
        "CONFLUENCE_USERNAME": "your-username",
        "CONFLUENCE_PASSWORD": "your-password"
      }
    }
  }
}
```

Restart Cursor. The `read_confluence_page` tool will appear in the agent's tool list.

---

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "finviet_confluence": {
      "command": "node",
      "args": ["/absolute/path/to/finviet-confluence-mcp/dist/index.js"],
      "env": {
        "CONFLUENCE_BASE_URL": "https://kb.finviet.com.vn",
        "CONFLUENCE_USERNAME": "your-username",
        "CONFLUENCE_PASSWORD": "your-password"
      }
    }
  }
}
```

Restart Claude Desktop. The tool will be available automatically in every conversation.

---

### Claude Code (CLI)

Add the server to your project or global Claude Code config:

```bash
claude mcp add finviet_confluence node /absolute/path/to/finviet-confluence-mcp/dist/index.js \
  -e CONFLUENCE_BASE_URL=https://kb.finviet.com.vn \
  -e CONFLUENCE_USERNAME=your-username \
  -e CONFLUENCE_PASSWORD=your-password
```

Verify the server is registered:

```bash
claude mcp list
```