ThisCalculator

Everyday

Local MCP Server with TypeScript: Setup Guide

Updated · Standard formula, shown below

This guide walks you through setting up a local Model Context Protocol (MCP) server using TypeScript. MCP lets AI assistants like Claude Desktop securely access your local files, databases, or custom tools through a standardized interface. By the end, you’ll have a working server that can expose your own tools and data to MCP-compatible clients.

What You’ll Need

  • Node.js 18 or newer (check with node -v)
  • npm or yarn package manager
  • Basic familiarity with TypeScript and command line
  • A code editor (VS Code recommended)
  • An MCP client to test with (e.g., Claude Desktop, or the MCP Inspector)

Step-by-Step

  1. Create a new project directory
    Run mkdir my-mcp-server && cd my-mcp-server and then npm init -y to create a package.json.
  2. Install dependencies
    Run npm install @modelcontextprotocol/sdk for the MCP SDK, and npm install -D typescript @types/node tsx for TypeScript and a dev runner.
  3. Configure TypeScript
    Create a tsconfig.json with:
    {
      "compilerOptions": {
        "target": "ES2022",
        "module": "NodeNext",
        "moduleResolution": "NodeNext",
        "outDir": "./dist",
        "rootDir": "./src",
        "strict": true,
        "esModuleInterop": true
      },
      "include": ["src/**/*"]
    }
  4. Create the server source file
    Make a src folder and add index.ts inside it.
  5. Write the basic server skeleton
    In index.ts, import the SDK and set up a server instance:
    import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
    import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
    
    const server = new McpServer({
      name: "my-local-server",
      version: "1.0.0"
    });
    
    // Tools and resources go here
    
    const transport = new StdioServerTransport();
    await server.connect(transport);
  6. Add a simple tool
    Register a tool that adds two numbers. This demonstrates the basic pattern:
    server.tool(
      "add",
      { a: z.number(), b: z.number() },
      async ({ a, b }) => ({
        content: [{ type: "text", text: String(a + b) }]
      })
    );

    You’ll need to install zod: npm install zod and import it: import { z } from "zod";

  7. Add a resource (optional but useful)
    Expose a simple text resource:
    server.resource(
      "greeting",
      "greeting://hello",
      async (uri) => ({
        contents: [{ uri: uri.href, text: "Hello from local MCP!" }]
      })
    );
  8. Build the project
    Add a build script to package.json: "build": "tsc", then run npm run build.
  9. Test locally with MCP Inspector
    Run npx @modelcontextprotocol/inspector node dist/index.js to open a web UI where you can test your tools and resources.
  10. Connect to an MCP client
    For Claude Desktop, edit the config file (e.g., claude_desktop_config.json) and add:
    {
      "mcpServers": {
        "my-server": {
          "command": "node",
          "args": ["/absolute/path/to/dist/index.js"]
        }
      }
    }

    Restart the client and your server should appear.

Common Mistakes

  • Forgetting to build TypeScript before running – the client runs the compiled JS, not the TS source.
  • Using relative paths in the client config – always use absolute paths to the built file.
  • Not installing zod when using tools – the SDK relies on it for schema validation.
  • Using CommonJS modules when your package.json doesn’t set "type": "module" – this causes import errors.
  • Missing the await on server.connect() – the process exits immediately otherwise.

Tips

  • Use tsx for development: npx tsx src/index.ts to run without building each time.
  • Keep your tools small and focused – each tool should do one thing well.
  • Add error handling inside tools to return meaningful messages instead of crashing the server.
  • Use environment variables for any sensitive paths or credentials, not hardcoded values.
  • Test with the Inspector before connecting to a full client – it shows exactly what the client sees.

Troubleshooting

  • Server starts but no tools appear in client – Check that you’ve built the project and the client config points to the correct file. Run the server manually in a terminal to see any errors.
  • “Cannot find module” errors – Ensure all dependencies are installed and you’re running from the project root. If using ESM, verify "type": "module" in package.json.
  • Tool calls time out – Your tool might be doing something slow (like network requests). Set a reasonable timeout in the client, or optimize the tool.
  • TypeScript compilation errors – Make sure your tsconfig is correct and that you’ve installed @types/node. Check that your imports use the .js extension when using NodeNext.
  • Client says “connection failed” – Verify the command and args are correct. Try running the command manually in a terminal to see if it produces any output. Also ensure the file has execute permissions.

Frequently Asked Questions

What exactly is MCP?

Model Context Protocol is an open standard that lets AI applications connect to external data sources and tools in a secure, controlled way. It’s like a USB port for AI – a universal interface.

Can I use this with any AI assistant?

Not all assistants support MCP yet. Currently, Claude Desktop and a few other clients do. Check the documentation of your preferred assistant to see if MCP is supported.

Do I need to expose my server to the internet?

No, that’s the point of a local server. It runs on your machine and only communicates with local clients over stdio or localhost. No external network exposure is needed.

How do I add more complex tools, like database access?

You can use any Node.js library inside your tool handlers. For example, install a database driver and query it within the tool function. Just be careful about security – validate inputs and avoid SQL injection.

Can I write the server in plain JavaScript instead?

Yes, the SDK works with JavaScript too. TypeScript is optional but recommended for type safety and better editor support. If you prefer JS, just skip the TypeScript setup and write your code in .js files.

How do I debug my server?

Use the MCP Inspector – it connects to your server and lets you inspect requests and responses. You can also add console.log statements; they’ll appear in the terminal where you run the server.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.