# mcp-tools

MCP (Model Context Protocol) servers for **Forgejo** and **NetBox**, packaged as standalone tools for any MCP-compatible client (Kiro, Cursor, Claude Desktop, etc.) and as CLI utilities for scripting and automation.

## Packages

| Package | Description |
|---------|-------------|
| `@mcp-tools/core` | Shared library — credential providers, config loading, HTTP client, write guard, logging |
| `forgejo-mcp-server` | MCP server + CLI for Forgejo/Gitea API (issues, PRs, branches, releases, webhooks, project boards) |
| `netbox-mcp-server` | MCP server + CLI for NetBox API (devices, IPs, VMs, services, cables, journals) |
| `authentik-mcp-server` | MCP server for Authentik API (users, groups, applications, providers, tokens) |
| `couchdb-mcp-server` | MCP server for CouchDB API (databases, users, permissions, replication, compaction) |

## Quick Start

### Install

```bash
# Run directly with npx (no install required)
npx forgejo-mcp-server --config ./forgejo-config.yaml
npx netbox-mcp-server --config ./netbox-config.yaml

# Or install globally
npm install -g forgejo-mcp-server netbox-mcp-server
```

### Configure

Create a config file (YAML or JSON):

```yaml
# forgejo-config.yaml
baseUrl: "https://your-forgejo-instance.example.com/api/v1"
credentialProvider:
  type: keepassxc       # or: env, file
  settings:
    databasePath: "/path/to/your.kdbx"
    keyfilePath: "/path/to/keyfile"
credentialId: "path/to/api-token"
logLevel: error
defaultOwner: "myorg"
defaultRepo: "myrepo"
```

Environment variables can override config file values:

| Variable | Overrides |
|----------|-----------|
| `MCP_CONFIG_PATH` | Config file location |
| `MCP_BASE_URL` | `baseUrl` |
| `MCP_CREDENTIAL_PROVIDER` | `credentialProvider.type` |
| `MCP_CREDENTIAL_ID` | `credentialId` |
| `MCP_LOG_LEVEL` | `logLevel` |

### Register with an MCP Client

**Kiro / Claude Desktop (`mcp.json`):**

```json
{
  "mcpServers": {
    "forgejo": {
      "command": "npx",
      "args": ["forgejo-mcp-server", "--config", "/path/to/forgejo-config.yaml"]
    },
    "netbox": {
      "command": "npx",
      "args": ["netbox-mcp-server", "--config", "/path/to/netbox-config.yaml"]
    }
  }
}
```

### CLI Mode

Each server doubles as a standalone CLI tool:

```bash
# List open issues
forgejo-mcp-server cli list_issues --state open

# Get a device from NetBox
netbox-mcp-server cli get_device --id 42

# Human-readable table output
forgejo-mcp-server cli list_repos --format table

# Write operations require --allow-write
forgejo-mcp-server cli create_issue --title "New issue" --allow-write
```

## Non-Destructive Mode

All write operations are blocked by default. Each write tool requires an explicit `allow_write: true` parameter (MCP) or `--allow-write` flag (CLI) per call. There is no global override — this ensures safety even in shared agent environments.

## Credential Providers

| Provider | Config `type` | How it resolves credentials |
|----------|---------------|----------------------------|
| KeePassXC | `keepassxc` | Spawns `keepassxc-cli` with configured DB and keyfile/password |
| Environment | `env` | Maps credential ID to uppercase env var |
| File | `file` | Reads `basePath/<credentialId>` from disk |
| macOS Keychain | `keychain` | Uses `security find-generic-password` |
| Docker Secrets | `docker-secrets` | Reads from `/run/secrets/` |
| Bitwarden | `bitwarden` | Uses `bw get password <item>` |

Providers can be chained with priority ordering — first successful resolve wins:

```yaml
credentialProvider:
  - type: env
    settings: { prefix: "FORGEJO_" }
  - type: keepassxc
    settings: { databasePath: "~/secrets.kdbx", keyfilePath: "~/.key" }
```

## Platform Support

- **Runtime:** Node.js 20+
- **OS:** macOS, Linux, Windows
- **MCP Clients:** Any client supporting stdio transport (Kiro, Cursor, Claude Desktop, etc.)

## Development

```bash
# Install dependencies
npm install

# Build all packages
npm run build

# Run tests
npm test

# Type-check without emitting
npm run lint
```

## Alternatives

If you only need one of these services, consider these dedicated MCP servers:

### Forgejo / Gitea
- [squarecows/forgejo-mcp](https://github.com/kunde21/forgejo-mcp) — TypeScript, stdio+HTTP, issues/PRs/repos
- [raohwork/forgejo-mcp](https://github.com/raohwork/forgejo-mcp) — Go binary
- [Official Gitea MCP](https://about.gitea.com/resources/tutorials/gitea-mcp-server) — Official Gitea project (API-compatible with Forgejo)

This project adds: web session support for project board operations, credential provider chain, CLI mode.

### NetBox
- [Official NetBox MCP](https://netboxlabscms.kinsta.cloud/docs/mcp/) — Official, read-only
- [alexkiwi1/netbox-mcp-rw](https://lobehub.com/mcp/alexkiwi1-netbox-mcp-rw) — Full CRUD

This project adds: bulk operations, available-IP finder, cable management, journal entries, CLI mode.

### Authentik
No dedicated Authentik MCP server exists in the community (as of 2026). This project provides the first one.

### CouchDB
- [couchdb-mcp-server](https://mcp.so/server/couchdb-mcp-server) — Basic document CRUD

This project adds: user/permission management, replication status, database compaction.

## AI Disclosure

This project's code and documentation were written with the assistance of LLMs:
- **Perplexity** and **Abacus** — requirements research and API evaluation
- **Kiro** (Claude) — spec authoring, implementation, testing, and documentation

All generated code was reviewed, tested (259 tests), and validated against live service instances by the project maintainer.

## License

GPL-3.0-or-later