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):
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:
$ 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.
Running the tests
$ 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:
$ 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:
pyproject.tomldeclares the version ranges users get (pip,uvx);uv.lockpins the exact versions used by CI, the release build's tests and the Docker image. Never edituv.lockby hand.- Test tooling (
pytest,testcontainers) lives in thedevdependency group, not independencies, so it is not shipped in the wheel or the Docker image. uv.lockcounts as a shipped file: a merged change to it releases a new version, because the Docker image installs from it.- Do not edit the
versionline inpyproject.toml; the release workflow writes it.
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:
- Import
mcp, the appropriateToolAnnotationsconstant, andannotatefrom..app - Import
execute_mikrotik_commandfrom..connector - Register tools using
@mcp.tool()decorators — always useannotate(BASE, "Title")(never a bare constant) - Follow the existing naming convention:
mikrotik_<action>_<resource> - Use type hints for all parameters (including
Literalfor fixed-value params) - Keep docstrings concise — a single sentence is ideal; avoid re-documenting every parameter
- Handle errors gracefully and return meaningful messages
annotate(BASE, "Title") — passing a bare
annotation constant skips the human-readable title and is considered incorrect.
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=...):
| Constant | Use for |
|---|---|
READ | Read-only queries (print, list, get, export) |
WRITE | Non-idempotent writes (add, create) |
WRITE_IDEMPOTENT | Idempotent writes (set, update, enable, disable) |
DESTRUCTIVE | Idempotent destructive operations (remove, flush) |
DANGEROUS | Non-idempotent destructive operations (reset, bulk create) |
3. Register your scope
Update src/mcp_mikrotik/app.py to import your new scope module:
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:
- Use testcontainers to spin up a real MikroTik RouterOS container
- Follow the existing test structure and naming conventions
- Test complete workflows (create, read, update, delete operations)
- Include proper cleanup to ensure tests are isolated
- Use the
@pytest.mark.integrationdecorator
"""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:
- Run integration tests:
$ uv run pytest tests/integration/test_my_feature_integration.py -v
- Use MCP Inspector: test your tools interactively using the MCP Inspector.
# Test your MCP server (stdio transport) $ npx @modelcontextprotocol/inspector uv run mcp-server-mikrotik
- Manual testing: test with a real MikroTik device to ensure commands work correctly.
Transport modes
The server supports three transport modes:
- stdio (default) — standard input/output, used by most MCP clients
- sse — Server-Sent Events over HTTP (exposes
/healthendpoint) - streamable-http — HTTP with streaming support (exposes
/healthendpoint)
Configure via CLI (--mcp.transport) or environment variable
(MIKROTIK_MCP__TRANSPORT).
Development guidelines
Code style
- Follow existing code patterns and naming conventions
- Use type hints for all function parameters and return values
- Use
Literaltypes for parameters with a fixed set of valid values - Use
Annotated[..., Field(...)]for numeric constraints (e.g. VLAN IDs) - Handle errors gracefully with meaningful error messages
- Log important operations using
ctx.info()/ctx.error()for client-visible logging
MikroTik command guidelines
- Always validate command syntax against MikroTik documentation
- Use proper escaping for string parameters (wrap in quotes when needed)
- Implement both creation and listing/querying functionality
- Consider implementing filtering options where appropriate
- Test commands on actual RouterOS before implementation
Testing requirements
- Write tests that cover the main functionality
- Ensure tests are isolated and clean up after themselves
- Use descriptive test names that explain what is being tested
- Include edge cases and error conditions in your tests
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:
- Update
docs/api-coverage.yml:status:implemented,partial,planned,legacyornot_applicable.tools: registered MCP tool names forimplemented,partialandlegacy.not_applicablemay also list the tool that explains it;plannedcommands must not list tools.params: manual argument names (vlan-id, notvlan_id;configuration.ssidfor 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: explainpartial,legacy,not_applicable, or a non-obvious caveat. Menu-levelnotesexplain 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.
- Run
uv run python scripts/api_coverage.py --write. - Run
uv run python scripts/api_coverage.py --check; CI runs the same check. - Run
uv run pytest -m "not integration". - Commit
docs/api-coverage.yml, the regenerateddocs/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
| Position | Label | Incremented by |
|---|---|---|
| 1 (MAJOR) | x.0.0.0 | Never — frozen at 0 |
| 2 (MINOR) | 0.x.0.0 | feat: commits |
| 3 (PATCH) | 0.0.x.0 | fix:, chore:, and other change commits |
| 4 (BUILD) | 0.0.0.x | Auto — commit count since the last version tag |
| — | no change | docs: commits |
0. Never use +semver: breaking or
+semver: major without explicit approval.
Quick reference
| Commit prefix | Example | Version change |
|---|---|---|
feat: | feat: add queue management tools | Minor bump: 0.5.0 → 0.6.0 |
fix: | fix: handle empty SSH response | Patch bump: 0.5.0 → 0.5.1 |
chore: | chore: update dependencies | Patch bump: 0.5.0 → 0.5.1 |
refactor: | refactor: simplify connector | Patch bump: 0.5.0 → 0.5.1 |
perf: | perf: cache SSH connection | Patch bump: 0.5.0 → 0.5.1 |
ci: | ci: add Python 3.13 to matrix | Patch bump: 0.5.0 → 0.5.1 |
test: | test: add queue smoke tests | Patch bump: 0.5.0 → 0.5.1 |
docs: | docs: update safe mode guide | No bump |
doc: | doc: fix typo | No bump |
| (untyped) | update something | Patch bump (fallback) |
+semver: breaking | footer tag | Major bump (emergency only) |
Format
<type>[optional scope]: <description> [optional body] [optional footer(s)]
Types
| Type | Description | Version effect |
|---|---|---|
feat | New feature or tool | Minor bump |
fix | Bug fix | Patch bump |
chore | Dependency updates, tooling | Patch bump |
refactor | Code restructuring | Patch bump |
perf | Performance improvement | Patch bump |
ci | CI/CD pipeline changes | Patch bump |
test | Test additions or updates | Patch bump |
style | Code formatting | Patch bump |
build | Build system changes | Patch bump |
revert | Reverting a previous commit | Patch bump |
docs / doc | Documentation only | No bump |
Scopes (optional)
Scopes indicate which area of the codebase is affected:
- Feature areas:
dhcp,dns,firewall,wireless,users,backup,queue,safe-mode,wireguard, etc. - Infrastructure:
api,cli,config,ssh,connector
Examples
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(safe-mode): handle ANSI escape sequences in <SAFE> prompt detection
Result: 0.5.0.0 → 0.5.1.0
chore: bump paramiko to 3.5.1 for CVE-2024-xxxx
Result: 0.5.0.0 → 0.5.1.0
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
- The PR is merged to
master - GitVersion calculates the new version from the commit history
- GitHub Actions builds the package with the calculated version
- Unit tests run across Python 3.10 / 3.11 / 3.12
- The package is published to PyPI (
skip-existing: true— duplicate versions are silently skipped, never fail the pipeline) - A git tag and GitHub Release are created automatically
You never need to manually bump version numbers or create tags.
Best practices
- Write clear commit messages — they become part of the release history and changelog
- One logical change per commit — makes version history clearer and easier to track
- Test before committing — failed builds don't get published
Branching strategy
Branches for new pull requests carry the issue number they address:
<type>/issue-<number>-<short-description>
<type>is one of the conventional commit types above (feat,fix,docs, …)<number>is the GitHub issue number the branch addresses- when the change has no issue, put
#in place of the number <short-description>is a few kebab-case words describing the change
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
- Fork the repository and create your feature branch from
master, named according to the branching strategy above - Implement your changes following the guidelines above
- Run all tests to ensure nothing is broken
- Test with MCP Inspector to verify tools work correctly
- Write descriptive commit messages following the format above
- 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)
- 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
- Check existing scope implementations for reference
- Review the MikroTik RouterOS documentation for command syntax
- Look at existing tests for testing patterns
- Open an issue if you need clarification on implementation details
Code review process
All contributions go through code review to ensure:
- Code follows project conventions and patterns
- MikroTik commands are correct and safe
- Tests provide adequate coverage
- Documentation is clear and complete
- Integration with existing codebase is smooth
Thank you for contributing to MikroTik MCP. Your additions help make RouterOS management more accessible through the Model Context Protocol.