MCP Servers for Cursor IDE

This project hosts multiple Model-Context-Protocol (MCP) servers designed to work with the Cursor IDE. MCP servers allow Cursor to leverage external tools and functionalities through a standardized communication protocol.

Table of Contents

• How To Use
• What is MCP?
• Project Structure
• Available Servers
• Server Configuration
• Available Tools
• Running the Servers
  • Quick Start
  • Running a Server Using the Helper Script
  • Running a Single Server Manually
  • Running All Servers
  • List Available Servers
• Testing Your MCP Server
• Adding a New MCP Server
• Understanding MCP Server Development
• Building the Project

Prerequisites

• Node.js (v16 or newer)
• npm or yarn

How To Use

1. Clone this repository:

   git clone https://github.com/yourusername/mcp-servers.git
   cd mcp-servers
   

2. Install dependencies and set up everything:

   npm run setup
   

   This command will:

   • Install all dependencies
   • Build the TypeScript project
   • Generate the necessary scripts for Cursor IDE integration
   • Provide instructions for setting up each server in Cursor

3. Configure Cursor IDE:

   • Open Cursor IDE
   • Go to Cursor Settings > Features > Mcp Servers
   • Click "Add New Mcp Server"
   • Enter a name for the server (e.g., "postgres")
   • For "Connection Type", select "command"
   • For "command", paste the path provided by the prepare script
   • Click "Save"

4. Environment Variables:

   • Copy the .env.example file to .env
   • Update the variables with your own credentials for each service

5. Use Mcp In Cursor IDE:

   • Open the composer
   • make sure you are using agent mode (claude 3.7 sonnet thinking is recommended)
   • submit the message you want to cursor

What is MCP?

Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to LLMs (Large Language Models). Think of MCP like a communication interface between Cursor IDE and external tools. MCP servers expose tools that can be used by Cursor IDE to enhance its capabilities.

Project Structure

mcp-servers/
├── src/
│   ├── servers/                  # Individual MCP servers
│   │   ├── postgres-server/      # PostgreSQL integration server
│   │   │   └── postgres-server.ts
│   │   ├── kubernetes-server/    # Kubernetes integration server
│   │   │   └── kubernetes-server.ts
│   │   ├── lease-pdf-server/     # PDF processing server
│   │   │   └── pdf-server.ts
│   │   └── ... (more servers)
│   ├── template/                 # Reusable templates
│   │   └── mcp-server-template.ts
│   ├── index.ts                  # Server runner utility
│   └── run-all.ts                # Script to run all servers
├── package.json
└── tsconfig.json

Available Servers

Currently, the following MCP servers are available:

1. PostgreSQL Server - Provides access to PostgreSQL databases for executing queries and retrieving schema information
2. Kubernetes Server - Provides access to Kubernetes clusters for managing pods, executing commands, and retrieving logs
3. PDF Server - Provides PDF document processing capabilities including text extraction, form field reading/writing, and PDF generation

Server Configuration

All servers are configured through environment variables. Create a .env file in the project root (or copy from .env.example) and configure the services you plan to use:

# PostgreSQL Configuration (for PostgreSQL server)
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=your_database_name
POSTGRES_USER=your_username
POSTGRES_PASSWORD=your_password
# POSTGRES_SSL_MODE=require # Uncomment if SSL is required
# POSTGRES_MAX_CONNECTIONS=10 # Optional: limit connection pool size

# Kubernetes Configuration (for Kubernetes server)
KUBECONFIG=/path/to/your/kubeconfig
# Alternative Kubernetes configuration:
# KUBE_API_URL=https://your-kubernetes-api-server
# KUBE_API_TOKEN=your-kubernetes-service-account-token

# PDF Server requires no additional configuration

Available Tools

PostgreSQL Server Tools

• mcp__get_database_info - Retrieves information about the connected database
• mcp__list_tables - Lists all tables in the current database schema
• mcp__get_table_structure - Gets the column definitions for a specific table
• mcp__execute_query - Executes a custom SQL query against the database

Kubernetes Server Tools

• get_pods - Retrieves pods from a specified namespace, with optional field and label selectors
• find_pods - Finds pods matching a name pattern in a specified namespace
• kill_pod - Deletes a pod in a specified namespace
• exec_in_pod - Executes a command in a specified pod and container
• get_pod_logs - Retrieves logs from a specified pod, with options for container, line count, and previous instance

PDF Server Tools

• read_pdf - Extracts text content and form field data from PDF documents

  • Parameters: input (string) - PDF file path or base64 encoded PDF content
  • Returns: JSON with success status, page count, extracted text, form fields, and metadata

• write_pdf - Creates new PDFs or modifies existing ones with content and form field updates

  • Parameters:
    • content (object) - Content to write (text and/or form fields)
    • templatePdf (optional string) - Template PDF file path or base64 content
    • outputPath (optional string) - Output file path (returns base64 if not provided)
  • Returns: JSON with success status, output path, and base64 data (if applicable)

Running the Servers

Quick Start

The setup command creates individual shell scripts for each server that can be used directly with Cursor IDE. After running npm run setup, you'll see instructions for each server configuration.

Running a Server Using the Helper Script

To run a specific server using the included helper script:

npm run server -- [server-name]

For example, to run the postgres server:

npm run server -- postgres

Or to run the PDF server:

npm run server -- pdf

This will automatically build the TypeScript code and start the server.

Running a Single Server Manually

To run a specific server manually:

npm run dev -- [server-name]

For example, to run the postgres server:

npm run dev -- postgres

Or to run the PDF server:

npm run dev -- pdf

Running All Servers

To run all servers simultaneously:

npm run dev:all

List Available Servers

To see a list of all available servers:

npm run dev -- --list

Testing Your MCP Server

Before connecting to Cursor IDE, you can test your MCP server's functionality:

1. Build your TypeScript project:

   npm run build
   

2. Run the server:

   npm run start:postgres
   

   Or for the PDF server:

   npm run start:pdf
   

3. For convenience, this project includes a ready-to-use script for Cursor:

   /path/to/mcp-servers/cursor-mcp-server.sh [server-name]
   

   You can use this script path directly in your Cursor IDE configuration. If no server name is provided, it defaults to the postgres server. Examples:

   # Run postgres server (default)
   /path/to/mcp-servers/cursor-mcp-server.sh
   
   # Run PDF server
   /path/to/mcp-servers/cursor-mcp-server.sh pdf
   
   # Run kubernetes server
   /path/to/mcp-servers/cursor-mcp-server.sh kubernetes
   

Adding a New MCP Server

To add a new MCP server to this project:

1. Create a new directory for your server under src/servers/:

   mkdir -p src/servers/my-new-server
   

2. Create your server implementation:

   // src/servers/my-new-server/my-new-server.ts
   import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
   import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
   import { z } from "zod";
   
   // Create an MCP server
   const server = new McpServer({
     name: "My New Server",
     version: "1.0.0",
   });
   
   // Add your tools
   server.tool(
     "my-tool",
     {
       param1: z.string().describe("Parameter description"),
       param2: z.number().describe("Parameter description"),
     },
     async ({ param1, param2 }) => {
       // Tool implementation
       return {
         content: [{ type: "text", text: `Result: ${param1} ${param2}` }],
       };
     }
   );
   
   // Start the server
   async function startServer() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.log("My New Server started and ready to process requests");
   }
   
   // Start the server if this file is run directly
   if (process.argv[1] === new URL(import.meta.url).pathname) {
     startServer();
   }
   
   export default server;
   

3. Add your server to the server list in src/index.ts and src/run-all.ts:

   const servers = [
     // ... existing servers
     {
       name: "my-new-server",
       displayName: "My New Server",
       path: join(__dirname, "servers/my-new-server/my-new-server.ts"),
     },
   ];
   

4. Update the package.json scripts (optional):

   "scripts": {
     // ... existing scripts
     "dev:my-new-server": "ts-node --esm src/servers/my-new-server/my-new-server.ts"
   }
   

Understanding MCP Server Development

When developing an MCP server, keep in mind:

1. Tools are the primary way to expose functionality. Each tool should:

   • Have a unique name
   • Define parameters using Zod for validation
   • Return results in a standardized format

2. Communication happens via stdio for Cursor integration.

3. Response Format is critical - MCP servers must follow the exact format:

   • Tools should return content with type: "text" for text responses
   • Avoid using unsupported types like type: "json" directly
   • For structured data, convert to JSON string and use type: "text"
   • Example:

     return {
       content: [
         { type: "text", text: "Human-readable response" },
         { type: "text", text: JSON.stringify(structuredData, null, 2) },
       ],
     };
     

Building the Project

To build the project, run:

npm run build