Content
# mcp-server-starter
Production-ready TypeScript template for building MCP (Model Context Protocol) servers. Works with Claude Code, Cursor, and any MCP client.
## Quick Start
```bash
# Clone the template
git clone https://github.com/fix2015/mcp-server-starter.git my-mcp-server
cd my-mcp-server
# Install dependencies
npm install
# Build
npm run build
# Run the server
npm start
```
## Project Structure
```
src/
index.ts # Server entry point — registers tools, resources, and prompts
tools/
example-tool.ts # Example tool implementation (process_text)
resources/
example-resource.ts # Example resource implementation (server-info)
```
## How to Add a New Tool
Create a new file in `src/tools/`:
```typescript
// src/tools/my-tool.ts
import { z } from "zod";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
export function registerMyTool(server: McpServer): void {
server.tool(
"my_tool_name",
"Description of what the tool does",
{
input: z.string().describe("Input parameter description"),
},
async ({ input }) => {
// Your tool logic here
return {
content: [{ type: "text", text: `Result: ${input}` }],
};
}
);
}
```
Then register it in `src/index.ts`:
```typescript
import { registerMyTool } from "./tools/my-tool.js";
registerMyTool(server);
```
## How to Add a New Resource
Create a new file in `src/resources/`:
```typescript
// src/resources/my-resource.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
export function registerMyResource(server: McpServer): void {
server.resource("my-resource", "custom://my-data", async (uri) => {
return {
contents: [
{
uri: uri.href,
mimeType: "application/json",
text: JSON.stringify({ key: "value" }),
},
],
};
});
}
```
Then register it in `src/index.ts`:
```typescript
import { registerMyResource } from "./resources/my-resource.js";
registerMyResource(server);
```
## Configuration
### Claude Code
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"my-server": {
"command": "node",
"args": ["/absolute/path/to/my-mcp-server/dist/index.js"]
}
}
}
```
### With Environment Variables
```json
{
"mcpServers": {
"my-server": {
"command": "node",
"args": ["/absolute/path/to/my-mcp-server/dist/index.js"],
"env": {
"API_KEY": "your-api-key"
}
}
}
}
```
## Development
```bash
# Watch mode — recompiles on file changes
npm run dev
# Test with the MCP Inspector
npm run inspect
```
## Included Examples
| Type | Name | Description |
|----------|----------------|--------------------------------------------------|
| Tool | `process_text` | Transforms text with uppercase and word counting |
| Resource | `server-info` | Returns server metadata as JSON |
| Prompt | `summarize` | Generates a summary prompt for a given topic |
## Deployment
### As a Local Server
Build and point your MCP client config to the built `dist/index.js`.
### As an npm Package
1. Update `name` in `package.json` to your package name
2. Run `npm publish`
3. Users can then run: `npx your-package-name`
### With Docker
```dockerfile
FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY dist/ ./dist/
ENTRYPOINT ["node", "dist/index.js"]
```
```bash
docker build -t my-mcp-server .
docker run -i my-mcp-server
```
## Requirements
- Node.js >= 18
- TypeScript >= 5.7
## License
MIT
