MikroTik MCP / Docs / Contributing

Contributing

Thank you for your interest in contributing to the MikroTik MCP server. This MCP (Model Context Protocol) server provides tools for managing MikroTik RouterOS devices. Contributors can extend functionality by adding new scopes (feature areas) and their corresponding tools.

Project structure

The codebase splits into a src/mcp_mikrotik/ package (the server and its feature scopes) and a tests/ tree (unit + integration suites):

repository layout
src/mcp_mikrotik/
├── scope/          # Feature modules — each file registers MCP tools via decorators
├── app.py          # MCPServer instance and ToolAnnotation constants
├── config.py       # Configuration (pydantic-settings, CLI args, env vars)
├── connector.py    # SSH connection handling
├── server.py       # Entry point — imports scopes, starts the server
└── mikrotik_ssh_client.py  # Low-level SSH client

tests/
├── integration/    # Integration tests using testcontainers
└── unit/           # Unit tests

Development setup

The project uses uv as its single Python toolchain; install uv first. After that, provisioning a working environment is two commands:

# clone and provision
$ git clone https://github.com/wiresage/mikrotik-mcp.git
$ cd mikrotik-mcp
$ uv sync --frozen

uv sync --frozen installs the exact versions pinned in uv.lock (including the dev dependency group) without re-resolving, so a clean checkout gets the same environment CI uses. uv creates and manages the .venv for you.

AGENTS
Working with an AI coding agent? The repository's AGENTS.md collects the setup commands, tool-writing rules and the RouterOS behaviour that has caused bugs before, so the agent has them up front.

Running the tests

# run the suites
$ uv run pytest                        # full suite
$ uv run pytest -m "not integration"   # unit tests only (no Docker needed)
$ uv run pytest -m integration         # integration tests (needs Docker)

No manual dependency install is needed — uv run executes against the locked environment.

Changing dependencies (regenerating the lockfile)

When you add, remove, or change a dependency in pyproject.toml, regenerate and commit the lockfile in the same PR:

# regenerate the lockfile
$ uv lock    # update uv.lock to match pyproject.toml
$ uv sync    # apply it to your environment

CI runs a lockfile-drift gate (uv lock --check): a PR that changed pyproject.toml without a matching uv.lock fails with a plain-language message saying the lockfile is out of date. Commit the updated uv.lock and the gate passes.

Keep these in mind when you touch dependencies:

Contributing new features

To add a new MikroTik feature/scope to the project, follow these five steps.

1. Create the scope implementation

Navigate to src/mcp_mikrotik/scope/ and create a new Python file for your feature (e.g. my_feature.py). Your scope file should:

TIP
Always register tools with annotate(BASE, "Title") — passing a bare annotation constant skips the human-readable title and is considered incorrect.
# Example structure — scope/my_feature.py
from typing import Optional
from mcp.server.mcpserver import Context
from ..connector import execute_mikrotik_command
from ..app import mcp, READ, WRITE, annotate

@mcp.tool(name="create_my_resource", annotations=annotate(WRITE, "Create My Resource"))
async def mikrotik_create_my_resource(
    ctx: Context,
    name: str,
    required_param: str,
    optional_param: Optional[str] = None,
    comment: Optional[str] = None
) -> str:
    """Creates a new resource on the MikroTik device."""
    await ctx.info(f"Creating resource: name={name}")

    cmd = f"/my/feature add name={name} param={required_param}"

    if optional_param:
        cmd += f" optional-param={optional_param}"
    if comment:
        cmd += f' comment="{comment}"'

    result = await execute_mikrotik_command(cmd, ctx)

    if "failure:" in result.lower() or "error" in result.lower():
        return f"Failed to create resource: {result}"

    return f"Resource created successfully:\n\n{result}"

2. Choose the right tool annotation

Import the appropriate annotation constant from app.py and pass it via @mcp.tool(annotations=...):

ConstantUse for
READRead-only queries (print, list, get, export)
WRITENon-idempotent writes (add, create)
WRITE_IDEMPOTENTIdempotent writes (set, update, enable, disable)
DESTRUCTIVEIdempotent destructive operations (remove, flush)
DANGEROUSNon-idempotent destructive operations (reset, bulk create)

3. Register your scope

Update src/mcp_mikrotik/app.py to import your new scope module:

# src/mcp_mikrotik/app.py
from mcp_mikrotik.scope import (  # noqa: F401
    backup, dhcp, dns, firewall_filter, firewall_nat,
    ip_address, ip_pool, logs, my_feature, routes, users, vlan, wireless,
)

The import triggers the @mcp.tool() decorators, which automatically register your tools with the MCP server. No manual registry is needed.

4. Write tests

Create tests in tests/ for unit tests or tests/integration/ for integration tests. Integration tests should:

# Example structure — based on test_mikrotik_user_integration.py
"""Integration tests for MikroTik my feature using testcontainers."""

import pytest
from mcp_mikrotik.scope.my_feature import (
    mikrotik_create_my_resource,
    mikrotik_list_my_resources
)

@pytest.mark.integration
class TestMikroTikMyFeatureIntegration:
    def test_01_create_resource(self, mikrotik_container):
        result = mikrotik_create_my_resource(
            name="test_resource",
            required_param="test_value"
        )
        assert "failed" not in result.lower()
        assert "test_resource" in result

    def test_02_list_resources(self, mikrotik_container):
        result = mikrotik_list_my_resources()
        assert "test_resource" in result

5. Test your implementation

Before submitting, ensure your implementation works:

  1. Run integration tests:
# run the integration suite for your feature
$ uv run pytest tests/integration/test_my_feature_integration.py -v
  1. Use MCP Inspector: test your tools interactively using the MCP Inspector.
# launch the inspector against your server
# Test your MCP server (stdio transport)
$ npx @modelcontextprotocol/inspector uv run mcp-server-mikrotik
  1. Manual testing: test with a real MikroTik device to ensure commands work correctly.

Transport modes

The server supports three transport modes:

Configure via CLI (--mcp.transport) or environment variable (MIKROTIK_MCP__TRANSPORT).

Development guidelines

Code style

MikroTik command guidelines

Testing requirements

API coverage

docs/api-coverage.yml is the source of truth for the RouterOS menus and commands the MCP intends to cover. docs/api-coverage.md is generated from it; never edit it by hand. The generated checklist is the checked/unchecked progress view for developers and users, and it is summarised on the API coverage page.

When adding or changing a tool:

  1. Update docs/api-coverage.yml:
    • status: implemented, partial, planned, legacy or not_applicable.
    • tools: registered MCP tool names for implemented, partial and legacy. not_applicable may also list the tool that explains it; planned commands must not list tools.
    • params: manual argument names (vlan-id, not vlan_id; configuration.ssid for nested arguments).
    • accepted_gaps: intentional omissions of manual arguments. Read-only fields and flags are excluded from the unmapped-argument check automatically, so do not add them just to silence warnings.
    • notes: explain partial, legacy, not_applicable, or a non-obvious caveat. Menu-level notes explain the scope; do not repeat the tool docstring.
    • manual_paths: menus documented as separate command pages. Include the parent page when it has arguments.
    • allow_missing_manual: only for commands with no standalone manual page.
    • server_tools: tools that do not map to one menu command (kind + note).
    • top-level excluded: out-of-scope menus, with a reason.
  2. Run uv run python scripts/api_coverage.py --write.
  3. Run uv run python scripts/api_coverage.py --check; CI runs the same check.
  4. Run uv run pytest -m "not integration".
  5. Commit docs/api-coverage.yml, the regenerated docs/api-coverage.md, and the tool code, tests and docs.

If the tool's parameters change, update its page under docs/reference/<area>/.

The Check API coverage workflow does not update the lockfile (docs/manual.lock.yml) or the manifest (docs/api-coverage.yml): review the api-coverage-report artifact, then update docs/manual.lock.yml and the manifest deliberately, run --write, and commit. Use --strict (or the workflow's strict input) when warnings should fail the run. The corpus is not committed; only the lockfile metadata is.

Commit format and versioning

This project uses GitVersion for automatic semantic versioning based on commit messages, and follows the Conventional Commits specification.

All pull requests merge directly to master. There are no develop or release branches. Every merge that contains a non-docs commit publishes a new package version automatically.

Version format

Published versions use a 4-part format: MAJOR.MINOR.PATCH.BUILD

PositionLabelIncremented by
1 (MAJOR)x.0.0.0Never — frozen at 0
2 (MINOR)0.x.0.0feat: commits
3 (PATCH)0.0.x.0fix:, chore:, and other change commits
4 (BUILD)0.0.0.xAuto — commit count since the last version tag
—no changedocs: commits
MAJOR
The major version is intentionally frozen at 0. Never use +semver: breaking or +semver: major without explicit approval.

Quick reference

Commit prefixExampleVersion change
feat:feat: add queue management toolsMinor bump: 0.5.0 → 0.6.0
fix:fix: handle empty SSH responsePatch bump: 0.5.0 → 0.5.1
chore:chore: update dependenciesPatch bump: 0.5.0 → 0.5.1
refactor:refactor: simplify connectorPatch bump: 0.5.0 → 0.5.1
perf:perf: cache SSH connectionPatch bump: 0.5.0 → 0.5.1
ci:ci: add Python 3.13 to matrixPatch bump: 0.5.0 → 0.5.1
test:test: add queue smoke testsPatch bump: 0.5.0 → 0.5.1
docs:docs: update safe mode guideNo bump
doc:doc: fix typoNo bump
(untyped)update somethingPatch bump (fallback)
+semver: breakingfooter tagMajor bump (emergency only)

Format

# commit anatomy
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types

TypeDescriptionVersion effect
featNew feature or toolMinor bump
fixBug fixPatch bump
choreDependency updates, toolingPatch bump
refactorCode restructuringPatch bump
perfPerformance improvementPatch bump
ciCI/CD pipeline changesPatch bump
testTest additions or updatesPatch bump
styleCode formattingPatch bump
buildBuild system changesPatch bump
revertReverting a previous commitPatch bump
docs / docDocumentation onlyNo bump

Scopes (optional)

Scopes indicate which area of the codebase is affected:

Examples

# feat: new feature, minor bump
feat(queue): add simple queue and queue tree management

Implements create, list, get, update, remove, enable, and disable
operations for queue types, queue trees, and simple queues.

Result: 0.5.0.0 → 0.6.0.0

# fix: bug fix, patch bump
fix(safe-mode): handle ANSI escape sequences in <SAFE> prompt detection

Result: 0.5.0.0 → 0.5.1.0

# chore: maintenance, patch bump
chore: bump paramiko to 3.5.1 for CVE-2024-xxxx

Result: 0.5.0.0 → 0.5.1.0

# docs: documentation, no bump
docs: add queue and safe-mode reference pages

Result: version unchanged — the pipeline skips the PyPI publish.

Mixed PR. When a PR contains both feat: and docs: commits, GitVersion picks the highest increment across all commits. The result is a minor bump.

Version release process

  1. The PR is merged to master
  2. GitVersion calculates the new version from the commit history
  3. GitHub Actions builds the package with the calculated version
  4. Unit tests run across Python 3.10 / 3.11 / 3.12
  5. The package is published to PyPI (skip-existing: true — duplicate versions are silently skipped, never fail the pipeline)
  6. A git tag and GitHub Release are created automatically

You never need to manually bump version numbers or create tags.

Best practices

Branching strategy

Branches for new pull requests carry the issue number they address:

# branch name format
<type>/issue-<number>-<short-description>
# examples
feat/issue-123-branch-one
fix/issue-#-branch-two

This makes every branch self-documenting: the type tells reviewers what kind of change to expect, and the issue number links the work back to its context (or # states explicitly that no issue exists, rather than leaving reviewers to search for one).

Submitting a pull request

  1. Fork the repository and create your feature branch from master, named according to the branching strategy above
  2. Implement your changes following the guidelines above
  3. Run all tests to ensure nothing is broken
  4. Test with MCP Inspector to verify tools work correctly
  5. Write descriptive commit messages following the format above
  6. Submit a pull request with:
    • Clear description of what you've added
    • Reference to any related issues
    • Screenshots or examples if applicable
    • Confirmation that tests pass
    • Indication of version bump impact (minor, major, patch, or none)
  7. Assign the pull request to yourself. Use Assignees in the sidebar, or open it with gh pr create --assignee @me. GitHub only lets people with write access set assignees; if you cannot, a maintainer assigns the pull request to you, so every contribution is listed under the contributor's name.

Getting help

Code review process

All contributions go through code review to ensure:

Thank you for contributing to MikroTik MCP. Your additions help make RouterOS management more accessible through the Model Context Protocol.