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

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

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

{
  "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

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:

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