rest-countries-mcp-opencode

A Model Context Protocol (MCP) server that provides access to the REST Countries API. This server exposes country information as tools that can be used by MCP-compatible AI assistants like Claude.

Features

• 🌍 Access comprehensive country data from REST Countries API
• 🔍 Search countries by name, code, currency, language, capital, region, and subregion
• 🏷️ Support for ISO country codes (alpha-2, alpha-3, numeric)
• ⚡ Built with TypeScript and @modelcontextprotocol/sdk for type safety and reliability

Installation

From npm

# Global installation (recommended for CLI use)
npm install -g rest-countries-mcp-opencode

# Or local installation
npm install rest-countries-mcp-opencode

From Source

# Clone the repository
git clone https://github.com/yourusername/rest-countries-mcp-opencode.git
cd rest-countries-mcp-opencode

# Install dependencies
npm install

# Build the project
npm run build

# Install globally
npm install -g .

Usage

Command Line

# Run the server
rest-countries-mcp-opencode

# Or if installed locally
npx rest-countries-mcp-opencode

With Claude Desktop

Add the following to your Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "rest-countries-mcp-opencode": {
      "command": "npx",
      "args": ["rest-countries-mcp-opencode"],
      "env": {}
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "rest-countries-mcp-opencode": {
      "command": "rest-countries-mcp-opencode",
      "args": [],
      "env": {}
    }
  }
}

Programmatic Usage

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { getClient } from 'rest-countries-mcp-opencode';

const client = getClient();
const countries = await client.getCountryByName('Japan');
console.log(countries);

Available Tools

get_country_by_name

Search for a country by its name.

Parameters:

• name (string): The name or partial name of the country to search for

Example:

{
  "name": "Japan"
}

get_country_by_code

Get a country by its ISO code (alpha-2, alpha-3, or numeric).

Parameters:

• code (string): The ISO code (e.g., "US", "USA", "840")

Example:

{
  "code": "US"
}

get_countries_by_currency

Get all countries that use a specific currency.

Parameters:

• currency (string): The currency code (e.g., "USD", "EUR")

Example:

{
  "currency": "EUR"
}

get_countries_by_language

Get all countries that speak a specific language.

Parameters:

• language (string): The language code (e.g., "en", "es", "zh")

Example:

{
  "language": "en"
}

get_countries_by_capital

Get countries by their capital city.

Parameters:

• capital (string): The capital city name

Example:

{
  "capital": "Washington"
}

get_countries_by_region

Get countries by continent/region.

Parameters:

• region (string): The region name (Africa, Americas, Asia, Europe, Oceania, Polar)

Example:

{
  "region": "Europe"
}

get_countries_by_subregion

Get countries by subregion.

Parameters:

• subregion (string): The subregion name (e.g., "Western Europe", "Eastern Asia")

Example:

{
  "subregion": "Western Europe"
}

get_countries_by_calling_code

Get countries by their calling code.

Parameters:

• callingCode (string): The calling code (e.g., "1", "44")

Example:

{
  "callingCode": "1"
}

get_all_countries

Get all countries (returns limited fields by default for performance).

Parameters:

• limit (number, optional): Maximum number of countries to return (default: 10, max: 50)
• fields (array, optional): Specific fields to return

Example:

{
  "limit": 5,
  "fields": ["name", "flags", "population"]
}

API Reference

This MCP server wraps the REST Countries API v3.1. For more information about the available data fields and response formats, please refer to the official documentation.

Development

Setting up the Development Environment

# Clone the repository
git clone https://github.com/yourusername/rest-countries-mcp-opencode.git
cd rest-countries-mcp-opencode

# Install dependencies
npm install

# Run in development mode with hot reload
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

# Build for production
npm run build

Project Structure

rest-countries-mcp-opencode/
├── bin/
│   └── server.js              # CLI entry point
├── src/
│   ├── index.ts               # Main MCP server implementation
│   ├── types.ts               # TypeScript type definitions
│   ├── api-client.ts          # REST Countries API client
│   └── formatter.ts           # Response formatting utilities
├── package.json               # npm package configuration
├── tsconfig.json              # TypeScript configuration
├── README.md                  # This file
├── CHANGELOG.md               # Version history
└── .npmignore                 # npm ignore file

Publishing to npm

Prerequisites

1. Create an npm account if you don't have one:

   • Go to https://www.npmjs.com/signup
   • Verify your email

2. Log in to npm:

   npm login

Publishing Steps

# 1. Update version in package.json
# 2. Update CHANGELOG.md
# 3. Build the project
npm run build

# 4. Run tests
npm test

# 5. Lint code
npm run lint

# 6. Publish to npm
npm publish

# Or publish with a tag (e.g., beta, next)
npm publish --tag beta

First Time Publishing (Scope)

If publishing to a scoped package (e.g., @yourname/rest-countries-mcp-opencode):

# Make the package public
npm access public

# Publish with scope
npm publish --access public

Automated Publishing with GitHub Actions

Create .github/workflows/npm-publish.yml:

name: Publish to npm

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm run build
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

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

Acknowledgments

• REST Countries for providing the free country data API
• Model Context Protocol for the standardization
• @modelcontextprotocol/sdk for the SDK