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

Quick Start

Install

# 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):

# 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:

Register with an MCP Client

Kiro / Claude Desktop (mcp.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:

# 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

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

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

# 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 — TypeScript, stdio+HTTP, issues/PRs/repos

• raohwork/forgejo-mcp — Go binary

• Official Gitea MCP — 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 — Official, read-only

• 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 — 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