This MCP server starter template provides a minimal yet functional MCP server using TypeScript and FastMCP, demonstrated with a weather service example. The repository organizes code into src/lib, src/services, and src/tools, showcasing how to structure utilities, service logic, and tool interfaces. After building, the server runs from the dist output, and you can connect with an MCP client to exercise the available tools (e.g., GET_WEATHER) to fetch weather data for a specified city. The weather tool demonstrates parameter validation (via Zod), HTTP utilities, and proper error handling, making it a practical starting point for expanding with additional tools and services.

To use the server locally, install dependencies, configure environment variables, build, and then run. The weather tool requires an OpenWeather API key, which you supply through an environment variable OPENWEATHER_API_KEY. Once running, you can connect with an MCP client and invoke tools exposed by the server, such as retrieving weather data for a given city. As you add more tools and services, register them in src/index.ts so they become available to MCP clients.

Prerequisites:

• Node.js (recommended LTS) and npm or pnpm installed
• Git installed
• Optional: pnpm if you follow the template defaults

Step-by-step installation:

1. Clone the repository or create a new project from the template git clone https://github.com/IQAIcom/mcp-server-starter.git cd mcp-server-starter

2. Install dependencies pnpm install

   or npm install

3. Configure environment variables (example for weather tool)

   Create a .env file at project root

   echo "OPENWEATHER_API_KEY=your_api_key_here" > .env

   or export directly in your shell

   export OPENWEATHER_API_KEY=your_api_key_here

4. Build the TypeScript project to JavaScript in dist/ pnpm run build

   or npm run build

5. Run the server node dist/index.js

   or use any start script provided by the project

6. (Optional) Run via pnpm dlx if you intend to publish or test locally via the package pnpm dlx your-published-package-name

7. Verify the MCP connection with a client and invoke available tools (e.g., GET_WEATHER for a city) as demonstrated in the template.

Tips and considerations:

• The template includes a weather service example to illustrate HTTP integration, parameter validation, and error handling. You can extend this by adding more tools under src/tools and corresponding services under src/services.
• Ensure OPENWEATHER_API_KEY is kept secure and added to .gitignore if you commit environment configuration.
• If you customize the bin or command name, update the package.json accordingly and rebuild.
• The project uses Biome for linting and formatting; you can customize lint-staged and Husky hooks as described in the template documentation.
• For release management, Changesets are supported; follow the template’s guidance to add changesets and publish releases when ready.