Skip to main content
Glama
aiopnet

MCP Nautobot Server

by aiopnet
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

MCP-Nautobot

MCP Python 3.10+ License: MIT Code style: black

A Model Context Protocol (MCP) server for Nautobot network automation platform. This project allows AI assistants to interact with your Nautobot instance, providing access to network inventory data.

Disclaimer: This project is not officially affiliated with Anthropic, Claude, or Nautobot. It is an independent implementation of the Model Context Protocol for Nautobot integration.

Features

  • Asynchronous API: Built with modern async Python

  • MCP Compatible: Works with Claude and other MCP-compatible AI assistants

  • Nautobot Integration: Query your network inventory data directly

  • Site Information: Retrieve detailed site location data

  • Device Details: Access device specifications and configurations

  • Network Topology: Visualize network connections and relationships

  • Role-based Access: Control data access by user role

  • Flexible Configuration: Customizable data presentation

Related MCP server: Notion MCP Server

Requirements

  • Python 3.10+

  • Nautobot instance with API access

  • Nautobot API token with appropriate permissions

Installation

# Clone the repository
git clone https://github.com/aiopnet/mcp-nautobot.git
cd mcp-nautobot

# Create and activate a virtual environment
# If uv is not installed, follow instructions at: https://github.com/astral-sh/uv
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv pip install -e .  # Requires pip 21.3+ for editable installs with pyproject.toml

Configuration

Copy the example environment file and update it with your settings:

cp .env.example .env
# Edit .env with your favorite editor

Environment Variables

Variable

Required

Description

Default

NAUTOBOT_URL

Yes

URL of your Nautobot instance

None

NAUTOBOT_TOKEN

Yes

API token with read permissions

None

MCP_PORT

No

Port for the MCP server to listen on

8000

MCP_HOST

No

Host for the MCP server to bind to

127.0.0.1

LOG_LEVEL

No

Logging level (DEBUG, INFO, WARNING, ERROR)

INFO

⚠️ Security Note: Never commit your .env file to version control. It contains sensitive API tokens.

For advanced configuration options, see docs/CONFIGURATION.md.

Usage

Running the Server

# Start the MCP server
python -m mcp_nautobot.server

# Or using the provided CLI
mcp-nautobot-server

The server will start on http://127.0.0.1:8000 by default.

Integrating with Claude Desktop

  1. Open Claude Desktop and navigate to Settings > Tools > Configure Custom Tools

  2. Add a new tool with the following details:

    • Name: Nautobot Network Data

    • Description: Access network inventory data from Nautobot

    • Schema Type: MCP

    • Endpoint URL: http://127.0.0.1:8000 (or your custom host/port)

  3. Save and test the connection

Now you can ask Claude questions about your network inventory:

  • "What sites do we have in the US West region?"

  • "Show me all devices in the Chicago datacenter"

  • "List all Cisco switches in our network"

  • "What's the IP address of the core router in Atlanta?"

Developer Guide

Testing

# Install development dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=mcp_nautobot

Code Style and Linting

This project follows PEP 8 guidelines and uses Black and isort for formatting.

# Format code
black mcp_nautobot tests
isort mcp_nautobot tests

# Lint code
flake8 mcp_nautobot tests
mypy mcp_nautobot

Roadmap

  • Device Configuration Retrieval: Access running device configurations

  • Topology Visualization: Generate network maps and diagrams

  • Multi-tenant Support: Enhanced role-based access control

  • Circuit Information: Data about WAN circuits and providers

  • Performance Data: Historical performance metrics integration

Contributing

Contributions are welcome! Please check out our Contributing Guide to get started.

If you encounter any issues or have feature requests, please open an issue.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgements


## Troubleshooting

If you encounter issues, check the [Troubleshooting Guide](docs/TROUBLESHOOTING.md) or open an issue on GitHub.

Available Tools

5 tools
get_ip_address_by_idB

Retrieve a specific IP address by its Nautobot ID

ParametersJSON Schema
NameRequiredDescriptionDefault
ip_idYesThe Nautobot ID of the IP address

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It states the tool retrieves data, implying a read-only operation, but doesn't disclose behavioral traits such as authentication needs, rate limits, error handling (e.g., what happens if the ID doesn't exist), or response format. The description is minimal and lacks context beyond the basic action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence with no wasted words. It front-loads the key information ('Retrieve a specific IP address') and efficiently specifies the method ('by its Nautobot ID'). Every part of the sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (single parameter, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose but lacks details on behavior, usage context, or output, leaving gaps that could hinder an AI agent. Without annotations or output schema, more completeness would be beneficial for a retrieval tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with the single parameter 'ip_id' documented as 'The Nautobot ID of the IP address'. The description adds no additional meaning beyond this, such as format examples or constraints. Baseline score of 3 is appropriate since the schema adequately covers the parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Retrieve') and resource ('a specific IP address'), and specifies the lookup method ('by its Nautobot ID'). It distinguishes from siblings like 'get_ip_addresses' (plural) by indicating retrieval of a single specific record. However, it doesn't explicitly contrast with 'search_ip_addresses' which might also retrieve IP addresses through different criteria.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when you have the Nautobot ID and want to fetch a single IP address, but it doesn't explicitly state when to use this versus alternatives like 'search_ip_addresses' or 'get_ip_addresses'. No guidance on prerequisites, error conditions, or exclusions is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_ip_addressesC

Retrieve IP addresses from Nautobot with filtering options

ParametersJSON Schema
NameRequiredDescriptionDefault
addressNoSpecific IP address to search for
prefixNoNetwork prefix to filter by (e.g., 10.0.0.0/24)
statusNoStatus to filter by (e.g., active, reserved, deprecated)
roleNoRole to filter by (e.g., loopback, secondary, anycast)
tenantNoTenant to filter by
vrfNoVRF to filter by
limitNoMaximum number of results to return (default: 100, max: 1000)
offsetNoNumber of results to skip for pagination (default: 0)

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions 'filtering options' but doesn't describe important behaviors like pagination details (implied by limit/offset parameters), authentication requirements, rate limits, error conditions, or what format the results will be returned in. The description is insufficient for a tool with 8 parameters and no output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that communicates the core purpose without unnecessary words. It's appropriately sized for a retrieval tool and front-loads the essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 8 parameters, no annotations, and no output schema, the description is inadequate. It doesn't explain what the tool returns, how results are structured, or important behavioral aspects like authentication needs or error handling. The description fails to compensate for the lack of structured metadata.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, the input schema already documents all 8 parameters thoroughly. The description adds no additional parameter semantics beyond mentioning 'filtering options' generically. The baseline score of 3 is appropriate since the schema does the heavy lifting for parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Retrieve') and resource ('IP addresses from Nautobot'), making the tool's purpose understandable. It distinguishes itself from 'get_ip_address_by_id' by retrieving multiple addresses with filtering, but doesn't explicitly differentiate from 'search_ip_addresses' which might offer similar functionality.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'search_ip_addresses' or 'get_ip_address_by_id'. It mentions 'filtering options' but doesn't specify use cases, prerequisites, or when other tools might be more appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_prefixesC

Retrieve network prefixes from Nautobot with filtering options

ParametersJSON Schema
NameRequiredDescriptionDefault
prefixNoSpecific network prefix to search for
statusNoStatus to filter by
siteNoSite to filter by
roleNoRole to filter by
tenantNoTenant to filter by
vrfNoVRF to filter by
limitNoMaximum number of results to return (default: 100, max: 1000)
offsetNoNumber of results to skip for pagination (default: 0)

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It mentions 'filtering options' but doesn't disclose key behaviors: whether this is a read-only operation, if it has rate limits, what authentication is required, or what the output format looks like. For a tool with 8 parameters and no annotations, this leaves significant gaps in understanding its behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core purpose ('Retrieve network prefixes from Nautobot') and adds a useful qualifier ('with filtering options'). There's no wasted verbiage or redundancy, making it appropriately concise for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 8 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain the return values, error conditions, or behavioral nuances like pagination (implied by 'limit' and 'offset' parameters). For a data retrieval tool with multiple filters, more context is needed to guide effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents all 8 parameters with their types, descriptions, and constraints. The description adds minimal value by mentioning 'filtering options' generically, but doesn't provide additional context or meaning beyond what's already in the schema. This meets the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Retrieve') and resource ('network prefixes from Nautobot'), making the purpose understandable. It also mentions 'with filtering options' which adds specificity. However, it doesn't explicitly differentiate from sibling tools like 'get_ip_addresses' or 'search_ip_addresses', which might retrieve similar network data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. With sibling tools like 'get_ip_addresses' and 'search_ip_addresses' available, there's no indication of whether this tool is for broader prefix retrieval, how it differs in scope, or any prerequisites for use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_ip_addressesB

Search IP addresses using a general query string

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSearch query (can match IP address, description, etc.)
limitNoMaximum number of results to return (default: 50, max: 500)

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It mentions 'Search' but doesn't disclose behavioral traits such as whether this is a read-only operation, potential rate limits, authentication needs, or what happens on no matches. The description is minimal and lacks critical context for safe and effective use.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is front-loaded and appropriately sized, with every element contributing to clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and no output schema, the description is incomplete for a search tool with 2 parameters. It covers the basic purpose but lacks details on behavior, return values, or error handling. However, the high schema coverage and simple structure keep it from being severely inadequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with clear documentation for 'query' (matches IP address, description, etc.) and 'limit' (default, max). The description adds no additional parameter semantics beyond what the schema provides, so it meets the baseline for high coverage without compensating value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Search') and resource ('IP addresses') with the method ('using a general query string'). It distinguishes from siblings like 'get_ip_address_by_id' (specific ID lookup) and 'get_ip_addresses' (likely unfiltered list) by specifying search functionality, though it doesn't explicitly name these alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for searching IP addresses with a query, suggesting it's for filtered retrieval versus unfiltered listing. However, it doesn't explicitly state when to use this tool over siblings like 'get_ip_addresses' or 'get_ip_address_by_id', nor does it provide exclusion criteria or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

test_connectionB

Test the connection to the Nautobot API

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It states the action ('Test') but doesn't explain what testing entails—whether it performs authentication, checks network connectivity, validates permissions, or returns specific status information. This leaves critical behavioral traits unspecified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, direct sentence with no wasted words. It's front-loaded with the core purpose and efficiently communicates the essential action without any structural fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no parameters, no output schema), the description is minimal but incomplete. It doesn't explain what 'testing' involves or what result to expect, which is crucial for a connection-testing tool with no annotations. More context on behavior or output would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and schema description coverage is 100%, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, earning a baseline high score for not adding unnecessary information.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Test') and target resource ('connection to the Nautobot API'), making the purpose immediately understandable. However, it doesn't distinguish this tool from its siblings (all data retrieval tools), which are unrelated to connection testing, so it misses the highest score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives or in what context it should be invoked. It doesn't mention prerequisites, timing, or relationship to the sibling tools, leaving usage entirely implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updates
    • First observedget_ip_address_by_id
    • First observedget_ip_addresses
    • First observedget_prefixes
    • First observedsearch_ip_addresses
    • First observedtest_connection
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.2/5.0

Scored across 5 tools

Disambiguation4/5

Most tools have distinct purposes: get_ip_address_by_id retrieves a specific IP, get_ip_addresses lists IPs with filters, get_prefixes handles prefixes, and test_connection is unique. However, get_ip_addresses and search_ip_addresses have some overlap, as both involve retrieving IP addresses, which could cause mild confusion about when to use each.

Naming Consistency5/5

All tool names follow a consistent snake_case pattern with clear verb_noun structures (e.g., get_ip_address_by_id, search_ip_addresses). The naming is predictable and readable across all five tools, with no deviations in style.

Tool Count4/5

With 5 tools, the count is reasonable for a server focused on IP address and prefix management in Nautobot. It's slightly lean but covers core retrieval and testing operations without feeling bloated, though it could benefit from more actions like create or update tools.

Completeness2/5

The tool set is severely incomplete for managing IP addresses and prefixes in Nautobot. It only provides retrieval and search operations, with no tools for creating, updating, or deleting IP addresses or prefixes. This leaves significant gaps that will hinder agents from performing full lifecycle management.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

  • hithereiamaliff-mcp-nextcloudOAuth
    ai.smithery

    A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…

    Cloud StorageFile SystemsWorkplace & Productivity
    238
  • mcpCOAuth
    com.wix

    A Model Context Protocol server for Wix AI tools

    Developer ToolsContent Management SystemsApp Automation
    216
  • TelnyxA
    com.telnyx.api

    The Telnyx MCP server is an official implementation of the Model Context Protocol that enables AI clients (like Claude Desktop, Cursor, and OpenAI Agents) to interact with Telnyx's telephony, messaging, and AI assistant APIs. It provides comprehensive capabilities including making and managing phone calls, sending SMS/MMS messages, purchasing and configuring phone numbers, creating AI assistants with custom instructions, managing cloud storage buckets, scraping and embedding website content, and handling integration secrets. The server exists as both a local implementation and a remotely hosted version, allowing developers to integrate real-world communication infrastructure directly into AI applications.

    CommunicationCloud PlatformsCloud Storage
    62
  • Apideck MCPA
    dev.apideck.mcp

    Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server

    Developer Tools
    42

Related MCP Servers