Tmux MCP Server

Instructions

Implementation Reference

• src/index.ts:59-77 (handler)

  The primary handler function for the "find-session" MCP tool. It takes the session name, calls the tmux helper to find it, and returns formatted JSON or error text.

  async ({ name }) => {
    try {
      const session = await tmux.findSessionByName(name);
      return {
        content: [{
          type: "text",
          text: session ? JSON.stringify(session, null, 2) : `Session not found: ${name}`
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `Error finding tmux session: ${error}`
        }],
        isError: true
      };
    }
  }

• src/index.ts:56-58 (schema)

  Input schema using Zod for the tool's 'name' parameter.

  {
    name: z.string().describe("Name of the tmux session to find")
  },

• src/index.ts:53-78 (registration)

  Registration of the "find-session" tool on the MCP server, specifying name, description, schema, and handler.

  server.tool(
    "find-session",
    "Find a tmux session by name",
    {
      name: z.string().describe("Name of the tmux session to find")
    },
    async ({ name }) => {
      try {
        const session = await tmux.findSessionByName(name);
        return {
          content: [{
            type: "text",
            text: session ? JSON.stringify(session, null, 2) : `Session not found: ${name}`
          }]
        };
      } catch (error) {
        return {
          content: [{
            type: "text",
            text: `Error finding tmux session: ${error}`
          }],
          isError: true
        };
      }
    }
  );

• src/tmux.ts:102-109 (helper)

  Supporting helper function that implements the session lookup logic by listing all sessions and filtering by name.

  export async function findSessionByName(name: string): Promise<TmuxSession | null> {
    try {
      const sessions = await listSessions();
      return sessions.find(session => session.name === name) || null;
    } catch (error) {
      return null;
    }
  }

• src/tmux.ts:8-13 (schema)

  TypeScript interface defining the structure of a TmuxSession object returned by the tool.

  export interface TmuxSession {
    id: string;
    name: string;
    attached: boolean;
    windows: number;
  }