Network MCP Server

⚠️ Educational Purpose Only: This is a proof-of-concept (POC) project designed for learning and demonstration purposes. It is not intended for production use.

A Model Context Protocol (MCP) server that provides network infrastructure data through a simple query interface. This server integrates with Kiro CLI and other MCP clients to extend AI capabilities with custom network infrastructure tools.

Overview

This MCP server exposes 4 specialized tools that allow querying network infrastructure information across multiple regions, countries, and data centers. It demonstrates how to build and integrate custom MCP servers with Kiro CLI (Amazon Q CLI).

Features

• Network Infrastructure Data: Query routers, switches, and firewalls across global data centers
• Multiple Tools: 4 specialized tools for querying, summarizing, searching, and comparing infrastructure
• Flexible Search: Search by region, country, or specific site name
• MCP Protocol: Built on the Model Context Protocol standard
• Kiro CLI Integration: Seamlessly integrates with Kiro CLI (Amazon Q CLI)

Prerequisites

• Node.js (v18 or higher recommended)
• npm or yarn
• Kiro CLI installed

Installation

From npm (Recommended)

npm install -g @jonmatum/network-mcp-server

From Source

git clone https://github.com/jonmatum/network-mcp-server.git
cd network-mcp-server
npm install
npm run build

Project Structure

network-mcp-server/
├── src/
│   ├── index.ts          # Main server implementation
│   └── network-data.json # Infrastructure data
├── build/
│   ├── index.js          # Compiled JavaScript
│   └── network-data.json # Copied data file
├── package.json          # Project dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── LICENSE              # MIT License
└── README.md            # This file

Configuration Files

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "node",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

Kiro CLI Integration

1. Configure MCP Server in Kiro CLI

Edit your Kiro CLI MCP configuration file at ~/.kiro/settings/mcp.json:

If installed globally via npm:

{
  "mcpServers": {
    "network-server": {
      "command": "network-mcp-server",
      "args": []
    }
  }
}

If using npx (no installation required):

{
  "mcpServers": {
    "network-server": {
      "command": "npx",
      "args": ["@jonmatum/network-mcp-server"]
    }
  }
}

If running from source:

{
  "mcpServers": {
    "network-server": {
      "command": "node",
      "args": ["/path/to/network-mcp-server/build/index.js"]
    }
  }
}

2. Verify Configuration

After adding the configuration, restart Kiro CLI or start a new chat session:

kiro-cli chat

3. Test the Integration

In Kiro CLI, you can now use the tools:

Can you get data for Tokyo?
Can you show me all sites in North America?
What infrastructure do we have in Germany?
Give me a regional summary for Europe
Find all sites with more than 15 routers
Compare Tokyo DC1 and London DC1

Available Tools

get_data

Retrieves network infrastructure data based on a query string.

Parameters:

• query (string, required): Search term for region, country, or site name

Example Queries:

• "North America" - Returns all North American sites
• "Japan" - Returns all Japanese data centers
• "London" - Returns London DC1 information

Response Format:

[
  {
    "region": "Asia Pacific",
    "country": "Japan",
    "sites": [
      {
        "site": "Tokyo DC1",
        "routers": 18,
        "switches": 60,
        "firewalls": 12
      }
    ]
  }
]

get_regional_summary

Get aggregated statistics for a region including total equipment counts and site counts.

Parameters:

• region (string, required): Region name (e.g., 'North America', 'Europe', 'Asia Pacific')

Response Format:

{
  "region": "Europe",
  "totals": {
    "sites": 15,
    "routers": 120,
    "switches": 450,
    "firewalls": 80
  },
  "countries": [
    {
      "country": "UK",
      "sites": 3,
      "routers": 26,
      "switches": 96,
      "firewalls": 17
    }
  ]
}

search_by_equipment

Find sites based on equipment count criteria.

Parameters:

• equipment_type (string, required): Equipment type: 'routers', 'switches', or 'firewalls'
• operator (string, required): Comparison operator: 'greater_than', 'less_than', or 'equals'
• count (number, required): Equipment count to compare against

Example: Find all sites with more than 15 routers

Response Format:

[
  {
    "region": "Europe",
    "country": "Germany",
    "site": "Frankfurt DC1",
    "routers": 16,
    "switches": 55,
    "firewalls": 11
  }
]

compare_sites

Compare infrastructure between multiple sites.

Parameters:

• sites (array, required): Array of site names to compare

Example: Compare "Tokyo DC1" and "London DC1"

Response Format:

[
  {
    "region": "Asia Pacific",
    "country": "Japan",
    "site": "Tokyo DC1",
    "routers": 18,
    "switches": 60,
    "firewalls": 12
  },
  {
    "region": "Europe",
    "country": "UK",
    "site": "London DC1",
    "routers": 14,
    "switches": 48,
    "firewalls": 9
  }
]

Data Coverage

The server includes infrastructure data for:

North America:

• USA: New York, Chicago, San Francisco, Dallas, Seattle
• Canada: Toronto, Vancouver, Montreal
• Mexico: Mexico City, Monterrey

Europe:

• UK: London, Manchester, Edinburgh
• Germany: Frankfurt, Berlin, Munich
• France: Paris, Marseille
• Netherlands: Amsterdam, Rotterdam
• Spain: Madrid, Barcelona
• Italy: Milan, Rome

Asia Pacific:

• Japan: Tokyo, Osaka, Nagoya
• Singapore: Singapore DC1, Singapore DC2
• Australia: Sydney, Melbourne, Brisbane
• South Korea: Seoul, Busan
• India: Mumbai, Bangalore, Delhi
• Hong Kong: Hong Kong DC1

South America:

• Brazil: São Paulo, Rio de Janeiro, Brasília
• Argentina: Buenos Aires, Córdoba
• Chile: Santiago
• Colombia: Bogotá

Middle East:

• UAE: Dubai, Abu Dhabi
• Saudi Arabia: Riyadh, Jeddah
• Israel: Tel Aviv

Africa:

• South Africa: Johannesburg, Cape Town
• Nigeria: Lagos
• Kenya: Nairobi

Development

Run in Development Mode

npm run dev

This uses tsx to run TypeScript directly without compilation.

Build for Production

npm run build

Compiles TypeScript to JavaScript in the build/ directory.

Start the Server

npm start

Runs the compiled JavaScript server.

Troubleshooting

Server Not Appearing in Kiro CLI

1. Check that the path in mcp.json is absolute and correct
2. Verify the server builds successfully: npm run build
3. Test the server manually: node build/index.js
4. Restart Kiro CLI

Build Errors

1. Ensure all dependencies are installed: npm install
2. Check Node.js version: node --version (should be v18+)
3. Verify TypeScript configuration in tsconfig.json

Tool Not Working

1. Check Kiro CLI logs for errors
2. Verify the tool name matches exactly: get_data
3. Ensure query parameter is a string

Extending the Server

Important: Shebang Line

The src/index.ts file must start with the shebang line for the executable to work when installed via npm:

#!/usr/bin/env node

This is required for the bin configuration in package.json to function correctly.

Adding New Tools

1. Add tool definition in ListToolsRequestSchema handler:

{
  name: "new_tool",
  description: "Description of new tool",
  inputSchema: {
    type: "object",
    properties: {
      param: { type: "string", description: "Parameter description" }
    },
    required: ["param"]
  }
}

2. Add tool handler in CallToolRequestSchema:

if (request.params.name === "new_tool") {
  // Tool implementation
  return {
    content: [{ type: "text", text: "Result" }]
  };
}

3. Rebuild: npm run build

Adding More Data

Edit src/network-data.json to add additional regions, countries, or sites following the existing structure.

MCP Protocol Resources

• MCP Specification
• MCP SDK Documentation
• Amazon Q CLI Documentation

License

MIT - See LICENSE file for details

Author

Jonatan Mata (@jonmatum)

Contributing

1. Fork the repository: https://github.com/jonmatum/network-mcp-server
2. Create a feature branch
3. Make your changes
4. Test with Kiro CLI or Claude Desktop
5. Submit a pull request

Support

For issues or questions:

• Open an issue: https://github.com/jonmatum/network-mcp-server/issues
• Check the troubleshooting section
• Review MCP protocol documentation